Home-based memory management interface. More...
#include <sofia-sip/su_types.h>#include <stdarg.h>
Go to the source code of this file.
Data Structures | |
| struct | su_home_s |
| Memory home structure. More... | |
Defines | |
| #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. | |
Home-based memory management interface.
| #define SU_ALLOC_H |
Defined when <sofia-sip/su_alloc.h> has been included.
| typedef SU_HOME_T su_home_t |
Memory home type.
Allocate a memory block.
Allocates a memory block of a given size.
If home is NULL, this function behaves exactly like malloc().
| home | pointer to home object | |
| size | size of the memory block to be allocated |
| 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).
| home | pointer to home object | |
| data | pointer to the memory block to be freed |
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.
| 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.
| home | pointer to a memory home | |
| data | pointer to a memory area possibly allocated though home |
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.
| 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().
| 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().
| 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.
| home | pointer to home object |
| int su_home_desctructor | ( | su_home_t * | home, | |
| void(*)(void *) | destructor | |||
| ) |
Set destructor function.
#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.
| home | pointer to a home object |
| 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.
| int su_home_has_parent | ( | su_home_t const * | home | ) |
Return true if home is a clone.
| 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.
| home | pointer to home object |
| 0 | when successful | |
| -1 | upon an error. |
| 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.
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.
| dst | destination home | |
| src | source home |
| 0 | if succesful | |
| -1 | upon an error |
| int su_home_mutex_lock | ( | su_home_t * | home | ) |
Increase refcount and obtain exclusive lock on home.
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).
| 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).
| size | size of home object |
The memory home object allocated with su_home_new() can be reclaimed with su_home_unref().
Preload a memory home.
The function su_home_preload() preloads a memory home.
| void* su_home_ref | ( | su_home_t const * | home | ) |
Create a new reference to a home object.
| size_t su_home_refcount | ( | su_home_t * | home | ) |
Return reference count of 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.
| home | memory home object to be converted thread-safe. |
| 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.
| int su_home_unlock | ( | su_home_t * | home | ) |
Release exclusive lock on home.
Release lock without decreasing refcount.
| 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.
| home | memory pool object to be unreferenced |
| 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.
| home | pointer to memory pool object | |
| memory | ponter to memory block |
| 1 | if memory has been allocated from home. | |
| 0 | otherwise |
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().
| home | pointer to memory pool object | |
| data | pointer to old memory block | |
| size | size of the memory block to be allocated |
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.
| home | pointer to memory pool object | |
| size | size of the structure |
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));
| 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.
| home | pointer to memory home (may be NULL) | |
| fmt | format string | |
| ... | argument list (must match with the fmt format string) |
| 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.
| home | pointer to memory home | |
| s1 | string to be first string | |
| s2 | string to be first string |
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.
| home | pointer to memory home | |
| ... | NULL-terminated list of strings to be concatenated |
NULL upon an error. 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.
| home | pointer to memory home | |
| s | string to be duplicated | |
| n | size of the resulting string |
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.
| home | pointer to memory home (may be NULL) | |
| fmt | format string | |
| ap | stdarg argument list (must match with the fmt format string) |
Allocate and zero a memory block.
Allocates a memory block with a given size from given memory home home and zeroes the allocated block.
| home | pointer to memory pool object | |
| size | size of the memory block |
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().