sofia-sip/su_alloc.h File Reference

Detailed Description

Home-based memory management interface.

Author:
Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>
Date:
Created: Thu Aug 19 01:12:25 1999 ppessi

#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...

Typedefs

typedef SU_HOME_T su_home_t
 Memory home type.
typedef 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.

Function Documentation

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.

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_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().

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.

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

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_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.

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()

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

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>

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().

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

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).

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().

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

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

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.

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().

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.

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.

int su_home_threadsafe (  su_home_t *  home  ) 
 

Convert su_home_t object to a thread-safe one.

Convert a memory home object as thread-safe by allocating mutexes and modifying function pointers in su_alloc.c module.

Parameters:
home memory home object to be converted thread-safe.
Return values:
0 when successful,
-1 upon an error.

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

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

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

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.

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.

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));
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.

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.

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.

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.

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.

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.

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.10devel - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.