Asterisk - The Open Source Telephony Project GIT-master-0bf3178
|
Object Model for Asterisk. More...
#include "asterisk/lock.h"
Go to the source code of this file.
Macros | |
#define | __ASTOBJ_HASH(type, hashes) type *next[1] |
#define | ASTOBJ_COMPONENTS(type) |
Add ASTOBJ components to a struct (with locking support). More... | |
#define | ASTOBJ_COMPONENTS_FULL(type, namelen, hashes) |
Add ASTOBJ components to a struct (with locking support). More... | |
#define | ASTOBJ_COMPONENTS_NOLOCK(type) ASTOBJ_COMPONENTS_NOLOCK_FULL(type,ASTOBJ_DEFAULT_NAMELEN,1) |
Add ASTOBJ components to a struct (without locking support). More... | |
#define | ASTOBJ_COMPONENTS_NOLOCK_FULL(type, namelen, hashes) |
Add ASTOBJ components to a struct (without locking support). More... | |
#define | ASTOBJ_CONTAINER_COMPONENTS(type) |
Create a container for ASTOBJs (with locking support). More... | |
#define | ASTOBJ_CONTAINER_COMPONENTS_NOLOCK(type) ASTOBJ_CONTAINER_COMPONENTS_NOLOCK_FULL(type,1,ASTOBJ_DEFAULT_BUCKETS) |
Create a container for ASTOBJs (without locking support). More... | |
#define | ASTOBJ_CONTAINER_COMPONENTS_NOLOCK_FULL(type, hashes, buckets) type *head |
Create a container for ASTOBJs (without locking support). More... | |
#define | ASTOBJ_CONTAINER_DESTROY(container) ASTOBJ_CONTAINER_DESTROY_FULL(container,1,ASTOBJ_DEFAULT_BUCKETS) |
Destroy a container. More... | |
#define | ASTOBJ_CONTAINER_DESTROY_FULL(container, hashes, buckets) |
Destroy a container. More... | |
#define | ASTOBJ_CONTAINER_DESTROYALL(container, destructor) |
Empty a container. More... | |
#define | ASTOBJ_CONTAINER_DUMP(fd, s, slen, container) ASTOBJ_CONTAINER_TRAVERSE(container, 1, do { ASTOBJ_DUMP(s,slen,iterator); ast_cli(fd, "%s", s); } while(0)) |
Dump information about all the objects in a container to a file descriptor. More... | |
#define | ASTOBJ_CONTAINER_FIND(container, namestr) |
Find an object in a container. More... | |
#define | ASTOBJ_CONTAINER_FIND_FULL(container, data, field, hashfunc, hashoffset, comparefunc) |
Find an object in a container. More... | |
#define | ASTOBJ_CONTAINER_FIND_UNLINK(container, namestr) |
Find and remove an object from a container. More... | |
#define | ASTOBJ_CONTAINER_FIND_UNLINK_FULL(container, data, field, hashfunc, hashoffset, comparefunc) |
Find and remove an object in a container. More... | |
#define | ASTOBJ_CONTAINER_INIT(container) ASTOBJ_CONTAINER_INIT_FULL(container,1,ASTOBJ_DEFAULT_BUCKETS) |
Initialize a container. More... | |
#define | ASTOBJ_CONTAINER_INIT_FULL(container, hashes, buckets) |
Initialize a container. More... | |
#define | ASTOBJ_CONTAINER_LINK(container, newobj) ASTOBJ_CONTAINER_LINK_FULL(container,newobj,(newobj)->name,name,ASTOBJ_DEFAULT_HASH,0,strcasecmp) |
Add an object to a container. More... | |
#define | ASTOBJ_CONTAINER_LINK_END(container, newobj) |
Add an object to the end of a container. More... | |
#define | ASTOBJ_CONTAINER_LINK_FULL(container, newobj, data, field, hashfunc, hashoffset, comparefunc) |
Add an object to a container. More... | |
#define | ASTOBJ_CONTAINER_LINK_START(container, newobj) |
Add an object to the front of a container. More... | |
#define | ASTOBJ_CONTAINER_MARKALL(container) ASTOBJ_CONTAINER_TRAVERSE(container, 1, ASTOBJ_MARK(iterator)) |
Mark all the objects in a container. More... | |
#define | ASTOBJ_CONTAINER_PRUNE_MARKED(container, destructor) |
Prune marked objects from a container. More... | |
#define | ASTOBJ_CONTAINER_RDLOCK(container) ast_mutex_lock(&(container)->_lock) |
Lock an ASTOBJ_CONTAINER for reading. More... | |
#define | ASTOBJ_CONTAINER_TRAVERSE(container, continue, eval) |
Iterate through the objects in a container. More... | |
#define | ASTOBJ_CONTAINER_UNLINK(container, obj) |
Remove an object from a container. More... | |
#define | ASTOBJ_CONTAINER_UNLINK_START(container) |
Remove an object from the front of a container. More... | |
#define | ASTOBJ_CONTAINER_UNLOCK(container) ast_mutex_unlock(&(container)->_lock) |
Unlock an ASTOBJ_CONTAINER. More... | |
#define | ASTOBJ_CONTAINER_UNMARKALL(container) ASTOBJ_CONTAINER_TRAVERSE(container, 1, ASTOBJ_UNMARK(iterator)) |
Unmark all the objects in a container. More... | |
#define | ASTOBJ_CONTAINER_WRLOCK(container) ast_mutex_lock(&(container)->_lock) |
Lock an ASTOBJ_CONTAINER for writing. More... | |
#define | ASTOBJ_DEFAULT_BUCKETS 256 |
#define | ASTOBJ_DEFAULT_HASH ast_strhash |
#define | ASTOBJ_DEFAULT_NAMELEN 80 |
#define | ASTOBJ_DUMP(s, slen, obj) snprintf((s),(slen),"name: %s\nobjflags: %u\nrefcount: %u\n\n", (obj)->name, (obj)->objflags, (obj)->refcount); |
Dump information about an object into a string. More... | |
#define | ASTOBJ_FLAG_MARKED (1 << 0) /* Object has been marked for future operation */ |
#define | ASTOBJ_INIT(object) |
Initialize an object. More... | |
#define | ASTOBJ_MARK(object) |
Mark an ASTOBJ by adding the ASTOBJ_FLAG_MARKED flag to its objflags mask. More... | |
#define | ASTOBJ_RDLOCK(object) ast_mutex_lock(&(object)->_lock) |
Lock an ASTOBJ for reading. More... | |
#define | ASTOBJ_REF(object) |
Increment an object reference count. More... | |
#define | ASTOBJ_TRYWRLOCK(object) ast_mutex_trylock(&(object)->_lock) |
#define | ASTOBJ_UNLOCK(object) ast_mutex_unlock(&(object)->_lock) |
Unlock a locked object. More... | |
#define | ASTOBJ_UNMARK(object) |
Unmark an ASTOBJ by subtracting the ASTOBJ_FLAG_MARKED flag from its objflags mask. More... | |
#define | ASTOBJ_UNREF(object, destructor) |
Decrement the reference count on an object. More... | |
#define | ASTOBJ_WRLOCK(object) ast_mutex_lock(&(object)->_lock) |
Lock an ASTOBJ for writing. More... | |
Object Model for Asterisk.
A set of macros implementing objects and containers. Macros are used for maximum performance, to support multiple inheritance, and to be easily integrated into existing structures without additional malloc calls, etc.
These macros expect to operate on two different object types, ASTOBJs and ASTOBJ_CONTAINERs. These are not actual types, as any struct can be converted into an ASTOBJ compatible object or container using the supplied macros.
Sample Usage:
Definition in file astobj.h.
#define ASTOBJ_COMPONENTS | ( | type | ) |
Add ASTOBJ components to a struct (with locking support).
type | The datatype of the object. |
This macro works like ASTOBJ_COMPONENTS_NOLOCK() except it includes locking support.
Sample Usage:
#define ASTOBJ_COMPONENTS_FULL | ( | type, | |
namelen, | |||
hashes | |||
) |
Add ASTOBJ components to a struct (with locking support).
type | The datatype of the object. |
namelen | The length to make the name char array. |
hashes | The number of containers the object can be present in. |
This macro adds components to a struct to make it an ASTOBJ and includes support for locking.
Sample Usage:
#define ASTOBJ_COMPONENTS_NOLOCK | ( | type | ) | ASTOBJ_COMPONENTS_NOLOCK_FULL(type,ASTOBJ_DEFAULT_NAMELEN,1) |
Add ASTOBJ components to a struct (without locking support).
type | The datatype of the object. |
This macro works like ASTOBJ_COMPONENTS_NOLOCK_FULL() except it only accepts a type and uses default values for namelen and hashes.
Sample Usage:
#define ASTOBJ_COMPONENTS_NOLOCK_FULL | ( | type, | |
namelen, | |||
hashes | |||
) |
Add ASTOBJ components to a struct (without locking support).
type | The datatype of the object. |
namelen | The length to make the name char array. |
hashes | The number of containers the object can be present in. |
This macro adds components to a struct to make it an ASTOBJ. This macro differs from ASTOBJ_COMPONENTS_FULL in that it does not create a mutex for locking.
Sample Usage:
#define ASTOBJ_CONTAINER_COMPONENTS | ( | type | ) |
Create a container for ASTOBJs (with locking support).
type | The type of objects the container will hold. |
This macro is used to create a container for ASTOBJs with locking support.
Sample Usage:
#define ASTOBJ_CONTAINER_COMPONENTS_NOLOCK | ( | type | ) | ASTOBJ_CONTAINER_COMPONENTS_NOLOCK_FULL(type,1,ASTOBJ_DEFAULT_BUCKETS) |
Create a container for ASTOBJs (without locking support).
type | The type of objects the container will hold. |
This macro is used to create a container for ASTOBJs without locking support.
Sample Usage:
Create a container for ASTOBJs (without locking support).
type | The type of objects the container will hold. |
hashes | Currently unused. |
buckets | Currently unused. |
This macro is used to create a container for ASTOBJs without locking support.
Sample Usage:
#define ASTOBJ_CONTAINER_DESTROY | ( | container | ) | ASTOBJ_CONTAINER_DESTROY_FULL(container,1,ASTOBJ_DEFAULT_BUCKETS) |
Destroy a container.
container | A pointer to the container to destory. |
This macro frees up resources used by a container. It does not operate on the objects in the container. To unlink the objects from the container use ASTOBJ_CONTAINER_DESTROYALL().
#define ASTOBJ_CONTAINER_DESTROY_FULL | ( | container, | |
hashes, | |||
buckets | |||
) |
Destroy a container.
container | A pointer to the container to destroy. |
hashes | Currently unused. |
buckets | Currently unused. |
This macro frees up resources used by a container. It does not operate on the objects in the container. To unlink the objects from the container use ASTOBJ_CONTAINER_DESTROYALL().
#define ASTOBJ_CONTAINER_DESTROYALL | ( | container, | |
destructor | |||
) |
Empty a container.
container | A pointer to the container to operate on. |
destructor | A destructor function to call on each object. |
This macro loops through a container removing all the items from it using ASTOBJ_UNREF(). This does not destroy the container itself, use ASTOBJ_CONTAINER_DESTROY() for that.
#define ASTOBJ_CONTAINER_DUMP | ( | fd, | |
s, | |||
slen, | |||
container | |||
) | ASTOBJ_CONTAINER_TRAVERSE(container, 1, do { ASTOBJ_DUMP(s,slen,iterator); ast_cli(fd, "%s", s); } while(0)) |
Dump information about all the objects in a container to a file descriptor.
fd | The file descriptor to write to. |
s | A string buffer, same as ASTOBJ_DUMP(). |
slen | The length of s, same as ASTOBJ_DUMP(). |
container | A pointer to the container to dump. |
This macro dumps a text representation of the name, objectflags, and refcount fields of all the objects in a container to the specified file descriptor.
#define ASTOBJ_CONTAINER_FIND | ( | container, | |
namestr | |||
) |
Find an object in a container.
container | A pointer to the container to search. |
namestr | The name to search for. |
Use this function to find an object with the specfied name in a container.
Find an object in a container.
container | A pointer to the container to search. |
data | The data to search for. |
field | The field/member of the container's objects to search. |
hashfunc | The hash function to use, currently not implemented. |
hashoffset | The hash offset to use, currently not implemented. |
comparefunc | The function used to compare the field and data values. |
This macro iterates through a container passing the specified field and data elements to the specified comparefunc. The function should return 0 when a match is found.
#define ASTOBJ_CONTAINER_FIND_UNLINK | ( | container, | |
namestr | |||
) |
Find and remove an object from a container.
container | A pointer to the container to operate on. |
namestr | The name of the object to remove. |
This macro iterates through a container and removes the first object with the specfied name from the container.
#define ASTOBJ_CONTAINER_FIND_UNLINK_FULL | ( | container, | |
data, | |||
field, | |||
hashfunc, | |||
hashoffset, | |||
comparefunc | |||
) |
Find and remove an object in a container.
container | A pointer to the container to search. |
data | The data to search for. |
field | The field/member of the container's objects to search. |
hashfunc | The hash function to use, currently not implemented. |
hashoffset | The hash offset to use, currently not implemented. |
comparefunc | The function used to compare the field and data values. |
This macro iterates through a container passing the specified field and data elements to the specified comparefunc. The function should return 0 when a match is found. If a match is found it is removed from the list.
#define ASTOBJ_CONTAINER_INIT | ( | container | ) | ASTOBJ_CONTAINER_INIT_FULL(container,1,ASTOBJ_DEFAULT_BUCKETS) |
Initialize a container.
container | A pointer to the container to initialize. |
This macro initializes a container. It should only be used on containers that support locking.
Sample Usage:
#define ASTOBJ_CONTAINER_INIT_FULL | ( | container, | |
hashes, | |||
buckets | |||
) |
Initialize a container.
container | A pointer to the container to initialize. |
hashes | Currently unused. |
buckets | Currently unused. |
This macro initializes a container. It should only be used on containers that support locking.
Sample Usage:
#define ASTOBJ_CONTAINER_LINK | ( | container, | |
newobj | |||
) | ASTOBJ_CONTAINER_LINK_FULL(container,newobj,(newobj)->name,name,ASTOBJ_DEFAULT_HASH,0,strcasecmp) |
#define ASTOBJ_CONTAINER_LINK_END | ( | container, | |
newobj | |||
) |
#define ASTOBJ_CONTAINER_LINK_FULL | ( | container, | |
newobj, | |||
data, | |||
field, | |||
hashfunc, | |||
hashoffset, | |||
comparefunc | |||
) |
Add an object to a container.
container | A pointer to the container to operate on. |
newobj | A pointer to the object to be added. |
data | Currently unused. |
field | Currently unused. |
hashfunc | Currently unused. |
hashoffset | Currently unused. |
comparefunc | Currently unused. |
Currently this function adds an object to the head of the list. One day it will support adding objects atthe position specified using the various options this macro offers.
#define ASTOBJ_CONTAINER_LINK_START | ( | container, | |
newobj | |||
) |
#define ASTOBJ_CONTAINER_MARKALL | ( | container | ) | ASTOBJ_CONTAINER_TRAVERSE(container, 1, ASTOBJ_MARK(iterator)) |
#define ASTOBJ_CONTAINER_PRUNE_MARKED | ( | container, | |
destructor | |||
) |
Prune marked objects from a container.
container | A pointer to the container to prune. |
destructor | A destructor function to call on each marked object. |
This macro iterates through the specfied container and prunes any marked objects executing the specfied destructor if necessary.
#define ASTOBJ_CONTAINER_RDLOCK | ( | container | ) | ast_mutex_lock(&(container)->_lock) |
#define ASTOBJ_CONTAINER_TRAVERSE | ( | container, | |
continue, | |||
eval | |||
) |
Iterate through the objects in a container.
container | A pointer to the container to traverse. |
continue | A condition to allow the traversal to continue. |
eval | A statement to evaluate in the iteration loop. |
This is macro is a little complicated, but it may help to think of it as a loop. Basically it iterates through the specfied containter as long as the condition is met. Two variables, iterator and next, are provided for use in your eval
statement. See the sample code for an example.
Sample Usage:
#define ASTOBJ_CONTAINER_UNLINK | ( | container, | |
obj | |||
) |
Remove an object from a container.
container | A pointer to the container to operate on. |
obj | A pointer to the object to remove. |
This macro iterates through a container and removes the specfied object if it exists in the container.
#define ASTOBJ_CONTAINER_UNLINK_START | ( | container | ) |
Remove an object from the front of a container.
container | A pointer to the container to operate on. |
This macro removes the first object in a container.
#define ASTOBJ_CONTAINER_UNLOCK | ( | container | ) | ast_mutex_unlock(&(container)->_lock) |
#define ASTOBJ_CONTAINER_UNMARKALL | ( | container | ) | ASTOBJ_CONTAINER_TRAVERSE(container, 1, ASTOBJ_UNMARK(iterator)) |
#define ASTOBJ_CONTAINER_WRLOCK | ( | container | ) | ast_mutex_lock(&(container)->_lock) |
#define ASTOBJ_DUMP | ( | s, | |
slen, | |||
obj | |||
) | snprintf((s),(slen),"name: %s\nobjflags: %u\nrefcount: %u\n\n", (obj)->name, (obj)->objflags, (obj)->refcount); |
Dump information about an object into a string.
s | A pointer to the string buffer to use. |
slen | The length of s. |
obj | A pointer to the object to dump. |
This macro dumps a text representation of the name, objectflags, and refcount fields of an object to the specfied string buffer.
#define ASTOBJ_FLAG_MARKED (1 << 0) /* Object has been marked for future operation */ |
#define ASTOBJ_INIT | ( | object | ) |
Initialize an object.
object | A pointer to the object to operate on. |
#define ASTOBJ_MARK | ( | object | ) |
Mark an ASTOBJ by adding the ASTOBJ_FLAG_MARKED flag to its objflags mask.
object | A pointer to the object to operate on. |
This macro "marks" an object. Marked objects can later be unlinked from a container using ASTOBJ_CONTAINER_PRUNE_MARKED().
#define ASTOBJ_RDLOCK | ( | object | ) | ast_mutex_lock(&(object)->_lock) |
#define ASTOBJ_REF | ( | object | ) |
#define ASTOBJ_TRYWRLOCK | ( | object | ) | ast_mutex_trylock(&(object)->_lock) |
#define ASTOBJ_UNLOCK | ( | object | ) | ast_mutex_unlock(&(object)->_lock) |
#define ASTOBJ_UNMARK | ( | object | ) |
Unmark an ASTOBJ by subtracting the ASTOBJ_FLAG_MARKED flag from its objflags mask.
object | A pointer to the object to operate on. |
#define ASTOBJ_UNREF | ( | object, | |
destructor | |||
) |
Decrement the reference count on an object.
object | A pointer the object to operate on. |
destructor | The destructor to call if the object is no longer referenced. It will be passed the pointer as an argument. |
This macro unreferences an object and calls the specfied destructor if the object is no longer referenced. The destructor should free the object if it was dynamically allocated.
#define ASTOBJ_WRLOCK | ( | object | ) | ast_mutex_lock(&(object)->_lock) |