Loading...
Searching...
No Matches
su_alloc.h File Reference
Memory Management Tutorial

Home-based memory management interface. More...

`#include <sofia-sip/su_types.h>`
`#include <stdarg.h>`
Include dependency graph for su_alloc.h:

Go to the source code of this file.

## Data Structures

struct | su_home_s
| Memory home structure. More...

## Macros

#define | SU_ALLOC_H
| Defined when <sofia-sip/su_alloc.h> has been included.

## Typedefs

typedef SU_HOME_T | su_home_t
| Memory home type.
typedef struct su_alock | su_alock_t
| Thread-locking function.

## Functions

void * | su_home_new (isize_t size))
| Create a new su_home_t object.
void * | su_home_ref (su_home_t const *)
| Create a new reference to a home object.
int | su_home_unref (su_home_t *)
| Unreference a su_home_t object.
size_t | su_home_refcount (su_home_t *home)
| Return reference count of home.
int | su_home_destructor (su_home_t *, void(*)(void *))
| Set destructor function.
int | su_home_desctructor (su_home_t *, void(*)(void *))
| Set destructor function.
void * | su_home_clone (su_home_t *parent, isize_t size))
| Clone a su_home_t object.
int | su_home_init (su_home_t *h)
| Initialize an su_home_t struct.
void | su_home_deinit (su_home_t *h)
| Free memory blocks allocated through home.
void | su_home_preload (su_home_t *h, isize_t n, isize_t size)
| Preload a memory home.
su_home_t * | su_home_auto (void *area, isize_t size)
| Preload a memory home from stack.
int | su_home_move (su_home_t *dst, su_home_t *src)
| Move allocations from a su_home_t object to another.
int | su_home_threadsafe (su_home_t *home)
| Convert su_home_t object to a thread-safe one.
int | su_home_has_parent (su_home_t const *home)
| Return true if home is a clone.
su_home_t * | su_home_parent (su_home_t const *home)
| Return home's parent home.
void | su_home_check (su_home_t const *home)
| Check home consistency.
int | su_home_check_alloc (su_home_t const *home, void const *data)
| Check if pointer has been allocated through home.
int | su_home_mutex_lock (su_home_t *home)
| Increase refcount and obtain exclusive lock on home.
int | su_home_mutex_unlock (su_home_t *home)
| Release exclusive lock on home and decrease refcount (if home is threadsafe).
int | su_home_lock (su_home_t *home)
| Obtain exclusive lock on home without increasing refcount.
int | su_home_trylock (su_home_t *home)
| Try to obtain exclusive lock on home without increasing refcount.
int | su_home_unlock (su_home_t *home)
| Release exclusive lock on home.
void * | su_alloc (su_home_t *h, isize_t size))
| Allocate a memory block.
void * | su_zalloc (su_home_t *h, isize_t size))
| Allocate and zero a memory block.
void * | su_salloc (su_home_t *h, isize_t size))
| Allocate a structure.
void * | su_realloc (su_home_t *h, void *data, isize_t size))
| Reallocate a memory block.
int | su_in_home (su_home_t *h, void const *data)
| Check if a memory block has been allocated from the home.
char * | su_strdup (su_home_t *home, char const *s))
| Duplicate a string, allocate memory from home.
char * | su_strcat (su_home_t *home, char const *s1, char const *s2))
| Concate two strings, allocate memory for result from home.
char * | su_strndup (su_home_t *home, char const *s, isize_t n))
| Duplicate a string with given size, allocate memory from home.
char * | su_strcat_all (su_home_t *home,...)))
| Concate multiple strings, allocate memory for result from home.
char * | su_sprintf (su_home_t *home, char const *fmt,...)))
| Copy a formatted string.
char * | su_vsprintf (su_home_t *home, char const *fmt, va_list ap))
| Copy a formatted string.
void | su_free (su_home_t *h, void *)
| Free a memory block.
int | su_home_is_threadsafe (su_home_t const *home)
| Check if a memory home is threadsafe.
su_home_t * | su_home_create (void))
| Create an su_home_t object.
void | su_home_destroy (su_home_t *h)
| Destroy a home object.

## Detailed Description

Home-based memory management interface.

Author
  Pekka Pessi Pekka.nosp@m..Pes.nosp@m.si@no.nosp@m.kia..nosp@m.com

Date
  Created: Thu Aug 19 01:12:25 1999 ppessi

## Function Documentation

## su_alloc()

void * su_alloc | ( | su_home_t * | home,
|  | isize_t | size )

Allocate a memory block.

Allocates a memory block of a given size.

If home is NULL, this function behaves exactly like malloc().

Parameters

  home | pointer to home object
  size | size of the memory block to be allocated

Returns
  This function returns a pointer to the allocated memory block or NULL if an error occurred.

## su_free()

void su_free | ( | su_home_t * | home,
|  | void * | data )

Free a memory block.

Frees a single memory block. The home must be the owner of the memory block (usually the memory home used to allocate the memory block, or NULL if no home was used).

Parameters

  home | pointer to home object
  data | pointer to the memory block to be freed

## su_home_auto()

su_home_t * su_home_auto | ( | void * | area,
|  | isize_t | size )

Preload a memory home from stack.

Initializes a memory home using an area allocated from stack. Poor man's alloca().

## su_home_check()

void su_home_check | ( | su_home_t const * | home | ) |

Check home consistency.

Ensures that the home structure and all memory blocks allocated through it are consistent. It can be used to catch memory allocation and usage errors.

Parameters

  home | Pointer to a memory home.

## su_home_check_alloc()

int su_home_check_alloc | ( | su_home_t const * | home,
|  | void const * | data )

Check if pointer has been allocated through home.

Parameters

  home | pointer to a memory home
  data | pointer to a memory area possibly allocated though home

Since
  New in 1.12.9

## su_home_clone()

void * su_home_clone | ( | su_home_t * | parent,
|  | isize_t | size )

Clone a su_home_t object.

Clone a secondary home object used to collect multiple memoryf allocations under one handle. The memory is freed either when the cloned home is destroyed or when the parent home is destroyed.

An independent home object is created if NULL is passed as parent argument.

Parameters

  parent | a parent object (may be NULL)
  size | size of home object

The memory home object allocated with su_home_clone() can be freed with su_home_unref().

Returns
  This function returns a pointer to an su_home_t object, or NULL upon an error.

## su_home_create()

su_home_t * su_home_create | ( | void |  | ) |

Create an su_home_t object.

Creates a home object. A home object is used to collect multiple memory allocations, so that they all can be freed by calling su_home_unref().

Returns
  This function returns a pointer to an su_home_t object, or NULL upon an error.

Deprecated
  Use su_home_new(sizeof (su_home_t)) instead

## su_home_deinit()

void su_home_deinit | ( | su_home_t * | home | ) |

Free memory blocks allocated through home.

Frees the memory blocks associated with the home object allocated. It does not free the home object itself. Use su_home_unref() to free the home object.

Parameters

  home | pointer to home object

See also
  su_home_init()

## su_home_desctructor()

int su_home_desctructor | ( | su_home_t * | home,
|  | void(* | destructor )(void *) )

Set destructor function.

Deprecated
  The su_home_destructor() was added in 1.12.4. The su_home_desctructor() is now defined as a macro expanding as su_home_destructor(). If you want to compile an application as binary compatible with earlier versions, you have to define su_home_desctructor as itself, e.g.,

#define su_home_desctructor su_home_desctructor
#include <sofia-sip/su_alloc.h>
su_alloc.h
Home-based memory management interface.

## su_home_destroy()

void su_home_destroy | ( | su_home_t * | home | ) |

Destroy a home object.

Frees all memory blocks associated with a home object. Note that the home object structure is not freed.

Parameters

  home | pointer to a home object

Deprecated
  su_home_destroy() is included for backwards compatibility only. Use su_home_unref() instead of su_home_destroy().

## su_home_destructor()

int su_home_destructor | ( | su_home_t * | home,
|  | void(* | destructor )(void *) )

Set destructor function.

The destructor function is called after the reference count of a su_home_t object reaches zero or a home object is deinitialized, but before any of the memory areas within the home object are freed.

Since
  New in 1.12.4. Earlier versions had su_home_desctructor() (spelling).

## su_home_init()

int su_home_init | ( | su_home_t * | home | ) |

Initialize an su_home_t struct.

Initializes an su_home_t structure. It can be used when the home structure is allocated from stack or when the home structure is part of an another object.

Parameters

  home | pointer to home object

Return values

  0 | when successful
  -1 | upon an error.

See also
  SU_HOME_INIT(), su_home_deinit(), su_home_new(), su_home_clone()

Bug
  Prior to 1.12.8 the su_home_t structure should have been initialized with SU_HOME_INIT() or otherwise zeroed before calling su_home_init().

## su_home_lock()

int su_home_lock | ( | su_home_t * | home | ) |

Obtain exclusive lock on home without increasing refcount.

Unless su_home_threadsafe() has been used to intialize locking on home object the function just returns -1.

Returns
  0 if successful, -1 if not threadsafe, error code otherwise.

See also
  su_home_mutex_lock(), su_home_unlock(), su_home_trylock().

Since
  New in 1.12.8

## su_home_move()

int su_home_move | ( | su_home_t * | dst,
|  | su_home_t * | src )

Move allocations from a su_home_t object to another.

Moves allocations made through the src home object under the dst home object. It is handy, for example, if an operation allocates some number of blocks that should be freed upon an error. It uses a temporary home and moves the blocks from temporary to a proper home when successful, but frees the temporary home upon an error.

If src has destructor, it is called before starting to move.

Parameters

  dst | destination home
  src | source home

Return values

  0 | if succesful
  -1 | upon an error

## su_home_mutex_lock()

int su_home_mutex_lock | ( | su_home_t * | home | ) |

Increase refcount and obtain exclusive lock on home.

Note
  The su_home_t structure must be created with su_home_new() or su_home_clone(), or initialized with su_home_init() before using this function.

In order to enable actual locking, use su_home_threadsafe(), too. Otherwise the su_home_mutex_lock() will just increase the reference count.

## su_home_mutex_unlock()

int su_home_mutex_unlock | ( | su_home_t * | home | ) |

Release exclusive lock on home and decrease refcount (if home is threadsafe).

See also
  su_home_unlock().

## su_home_new()

void * su_home_new | ( | isize_t | size | ) |

Create a new su_home_t object.

Create a home object used to collect multiple memory allocations under one handle. The memory allocations made using this home object is freed either when this home is destroyed.

The maximum size of a home object is INT_MAX (2 gigabytes).

Parameters

  size | size of home object

The memory home object allocated with su_home_new() can be reclaimed with su_home_unref().

Returns
  This function returns a pointer to an su_home_t object, or NULL upon an error.

## su_home_preload()

void su_home_preload | ( | su_home_t * | home,
|  | isize_t | n,
|  | isize_t | isize )

Preload a memory home.

The function su_home_preload() preloads a memory home.

## su_home_trylock()

int su_home_trylock | ( | su_home_t * | home | ) |

Try to obtain exclusive lock on home without increasing refcount.

Returns
  0 if successful, -1 if not threadsafe, EBUSY if already locked, error code otherwise.

See also
  su_home_lock(), su_home_unlock().

Since
  New in 1.12.8

## su_home_unlock()

int su_home_unlock | ( | su_home_t * | home | ) |

Release exclusive lock on home.

Release lock without decreasing refcount.

Returns
  0 if successful, -1 if not threadsafe, error code otherwise.

See also
  su_home_lock(), su_home_trylock(), su_home_mutex_unlock().

Since
  New in 1.12.8

## su_home_unref()

int su_home_unref | ( | su_home_t * | home | ) |

Unreference a su_home_t object.

Decrements the reference count on home object and destroys and frees it and the memory allocations using it if the reference count reaches 0.

Parameters

  home | memory pool object to be unreferenced

Return values

  1 | if object was freed
  0 | if object is still alive

## su_in_home()

int su_in_home | ( | su_home_t * | home,
|  | void const * | memory )

Check if a memory block has been allocated from the home.

Check if the given memory block has been allocated from the home.

Parameters

  home | pointer to memory pool object
  memory | ponter to memory block

Return values

  1 | if memory has been allocated from home.
  0 | otherwise

Since
  New in 1.12.4.

## su_realloc()

void * su_realloc | ( | su_home_t * | home,
|  | void * | data,
|  | isize_t | size )

Reallocate a memory block.

Allocates a memory block of size bytes. It copies the old block contents to the new block and frees the old block.

If home is NULL, this function behaves exactly like realloc().

Parameters

  home | pointer to memory pool object
  data | pointer to old memory block
  size | size of the memory block to be allocated

Returns
  A pointer to the allocated memory block or NULL if an error occurred.

## su_salloc()

void * su_salloc | ( | su_home_t * | home,
|  | isize_t | size )

Allocate a structure.

Allocates a structure with a given size, zeros it, and initializes the size field to the given size. The size field is an int at the beginning of the structure. Note that it has type of int.

Parameters

  home | pointer to memory pool object
  size | size of the structure

Example
  The structure is defined and allocated as follows:
  struct test {
  int tst_size;
  char *tst_name;
  void *tst_ptr[3];
  };
  struct test *t;
  ...
  t = su_salloc(home, sizeof (*t));
  assert(t && t->t_size == sizeof (*t));
  su_salloc
  void * su_salloc(su_home_t *h, isize_t size))
  Allocate a structure.
  Definition su_alloc.c:1512
  After calling su_salloc() we get a pointer t to a struct test, initialized to zero except the tst_size field, which is initialized to sizeof (*t).

Returns
  A pointer to the allocated structure, or NULL upon an error.

## su_sprintf()

char * su_sprintf | ( | su_home_t * | home,
|  | char const * | fmt,
|  |  | ... )

Copy a formatted string.

The function su_sprintf() print a string according to a fmt like printf() or snprintf(). The resulting string is copied to a memory area freshly allocated from a memory home. The returned string is reclaimed when home is destroyed. It can explicitly be freed with su_free() or free() if home is NULL.

Parameters

  home | pointer to memory home (may be NULL)
  fmt | format string
  ... | argument list (must match with the fmt format string)

Returns
  A pointer to a fresh copy of formatting result, or NULL upon an error.

## su_strcat()

char * su_strcat | ( | su_home_t * | home,
|  | char const * | s1,
|  | char const * | s2 )

Concate two strings, allocate memory for result from home.

Concatenate the strings s1 and s2. The `strlen(s1)+strlen(s2)+1` bytes is allocated from home, the contents of s1 and s2 is copied to the newly allocated memory area, and pointer to the concatenated string is returned.

Parameters

  home | pointer to memory home
  s1 | string to be first string
  s2 | string to be first string

Returns
  Pointer to the newly created string is returned, or `NULL` upon an error.

## su_strcat_all()

char * su_strcat_all | ( | su_home_t * | home,
|  |  | ... )

Concate multiple strings, allocate memory for result from home.

Concatenate the strings in list. The lenght of result is calculate, result is allocated from home, the contents of strings is copied to the newly allocated memory arex, and pointer to the concatenated string is returned.

Parameters

  home | pointer to memory home
  ... | NULL-terminated list of strings to be concatenated

Returns
  Pointer to the newly created string is returned, or `NULL` upon an error.

## su_strndup()

char * su_strndup | ( | su_home_t * | home,
|  | char const * | s,
|  | isize_t | n )

Duplicate a string with given size, allocate memory from home.

The function su_strndup() duplicates the string s. It allocates `n+1` bytes from home, copies the contents of s to the newly allocated memory, and returns pointer to the duplicated string. The duplicated string is always NUL-terminated.

Parameters

  home | pointer to memory home
  s | string to be duplicated
  n | size of the resulting string

Returns
  The function su_strndup() returns pointer to the newly created string, or `NULL` upon an error.

## su_vsprintf()

char * su_vsprintf | ( | su_home_t * | home,
|  | char const * | fmt,
|  | va_list | ap )

Copy a formatted string.

The function su_vsprintf() print a string according to a fmt like vprintf() or vsnprintf(). The resulting string is copied to a memory area fresly allocated from a memory home. The returned string is reclaimed when home is destroyed. It can explicitly be freed with su_free() or free() if home is NULL.

Parameters

  home | pointer to memory home (may be NULL)
  fmt | format string
  ap | stdarg argument list (must match with the fmt format string)

Returns
  A pointer to a fresh copy of formatting result, or NULL upon an error.

## su_zalloc()

void * su_zalloc | ( | su_home_t * | home,
|  | isize_t | size )

Allocate and zero a memory block.

Allocates a memory block with a given size from given memory home home and zeroes the allocated block.

Parameters

  home | pointer to memory pool object
  size | size of the memory block

Note
  The memory home pointer home may be `NULL`. In that case, the allocated memory block is not associated with any memory home, and it must be freed by calling su_free() or free().

Returns
  The function su_zalloc() returns a pointer to the allocated memory block, or NULL upon an error.

Sofia-SIP 1.12.11devel - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.