Asterisk - The Open Source Telephony Project  21.4.1
Data Structures | Macros | Typedefs | Enumerations | Functions
astobj2.h File Reference
#include "asterisk/compat.h"
#include "asterisk/lock.h"
#include "asterisk/linkedlists.h"
#include "asterisk/inline_api.h"

Go to the source code of this file.

Data Structures

struct  ao2_global_obj
 
struct  ao2_iterator
 When we need to walk through a container, we use an ao2_iterator to keep track of the current position. More...
 
struct  ao2_weakproxy
 This struct should be opaque, but it's size is needed. More...
 

Macros

#define ao2_alloc_with_lockobj(data_size, destructor_fn, lockobj, tag)   __ao2_alloc_with_lockobj((data_size), (destructor_fn), (lockobj), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Allocate and initialize an object with separate locking. More...
 
#define ao2_callback_data(container, flags, cb_fn, arg, data)   __ao2_callback_data((container), (flags), (cb_fn), (arg), (data), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_cleanup(obj)   __ao2_cleanup_debug((obj), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define AO2_FIELD_CMP_FN(stype, fn_suffix, field, key_cmp, partial_key_cmp, transform, argconst)
 
#define AO2_FIELD_HASH_FN(stype, field, hash_fn)
 Creates a hash function for a structure field. More...
 
#define AO2_FIELD_TRANSFORM_CMP_FN(cmp)   ((cmp) ? 0 : CMP_MATCH)
 
#define AO2_FIELD_TRANSFORM_SORT_FN(cmp)   (cmp)
 
#define ao2_find(container, arg, flags)   __ao2_find((container), (arg), (flags), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_global_obj_ref(holder)   __ao2_global_obj_ref(&holder, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
 Get a reference to the object stored in the global holder. More...
 
#define ao2_global_obj_release(holder)   __ao2_global_obj_replace_unref(&holder, NULL, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
 Release the ao2 object held in the global holder. More...
 
#define ao2_global_obj_replace(holder, obj)   __ao2_global_obj_replace(&holder, (obj), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
 Replace an ao2 object in the global holder. More...
 
#define ao2_global_obj_replace_unref(holder, obj)   __ao2_global_obj_replace_unref(&holder, (obj), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
 Replace an ao2 object in the global holder, throwing away any old object. More...
 
#define AO2_GLOBAL_OBJ_STATIC(name)
 Define a global object holder to be used to hold an ao2 object, statically initialized. More...
 
#define ao2_iterator_next(iter)   __ao2_iterator_next((iter), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_lock(a)   __ao2_lock(a, AO2_LOCK_REQ_MUTEX, __FILE__, __PRETTY_FUNCTION__, __LINE__, #a)
 
#define ao2_rdlock(a)   __ao2_lock(a, AO2_LOCK_REQ_RDLOCK, __FILE__, __PRETTY_FUNCTION__, __LINE__, #a)
 
#define AO2_STRING_FIELD_CASE_CMP_FN(stype, field)   AO2_FIELD_CMP_FN(stype, _cmp_fn, field, strcasecmp, strncasecmp, AO2_FIELD_TRANSFORM_CMP_FN,)
 
#define AO2_STRING_FIELD_CASE_HASH_FN(stype, field)   AO2_FIELD_HASH_FN(stype, field, ast_str_case_hash)
 
#define AO2_STRING_FIELD_CASE_SORT_FN(stype, field)   AO2_FIELD_CMP_FN(stype, _sort_fn, field, strcasecmp, strncasecmp, AO2_FIELD_TRANSFORM_SORT_FN, const)
 
#define AO2_STRING_FIELD_CMP_FN(stype, field)   AO2_FIELD_CMP_FN(stype, _cmp_fn, field, strcmp, strncmp, AO2_FIELD_TRANSFORM_CMP_FN,)
 Creates a compare function for a structure string field. More...
 
#define AO2_STRING_FIELD_HASH_FN(stype, field)   AO2_FIELD_HASH_FN(stype, field, ast_str_hash)
 Creates a hash function for a structure string field. More...
 
#define AO2_STRING_FIELD_SORT_FN(stype, field)   AO2_FIELD_CMP_FN(stype, _sort_fn, field, strcmp, strncmp, AO2_FIELD_TRANSFORM_SORT_FN, const)
 Creates a sort function for a structure string field. More...
 
#define ao2_t_callback_data(container, flags, cb_fn, arg, data, tag)   __ao2_callback_data((container), (flags), (cb_fn), (arg), (data), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 ao2_callback_data() is a generic function that applies cb_fn() to all objects in a container. It is functionally identical to ao2_callback() except that instead of taking an ao2_callback_fn *, it takes an ao2_callback_data_fn *, and allows the caller to pass in arbitrary data. More...
 
#define ao2_t_cleanup(obj, tag)   __ao2_cleanup_debug((obj), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_t_find(container, arg, flags, tag)   __ao2_find((container), (arg), (flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_t_global_obj_ref(holder, tag)   __ao2_global_obj_ref(&holder, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
 
#define ao2_t_global_obj_release(holder, tag)   __ao2_global_obj_replace_unref(&holder, NULL, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
 
#define ao2_t_global_obj_replace(holder, obj, tag)   __ao2_global_obj_replace(&holder, (obj), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
 
#define ao2_t_global_obj_replace_unref(holder, obj, tag)   __ao2_global_obj_replace_unref(&holder, (obj), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
 
#define ao2_t_iterator_next(iter, tag)   __ao2_iterator_next((iter), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_trylock(a)   __ao2_trylock(a, AO2_LOCK_REQ_MUTEX, __FILE__, __PRETTY_FUNCTION__, __LINE__, #a)
 
#define ao2_tryrdlock(a)   __ao2_trylock(a, AO2_LOCK_REQ_RDLOCK, __FILE__, __PRETTY_FUNCTION__, __LINE__, #a)
 
#define ao2_trywrlock(a)   __ao2_trylock(a, AO2_LOCK_REQ_WRLOCK, __FILE__, __PRETTY_FUNCTION__, __LINE__, #a)
 
#define ao2_unlock(a)   __ao2_unlock(a, __FILE__, __PRETTY_FUNCTION__, __LINE__, #a)
 
#define ao2_weakproxy_find(c, arg, flags, tag)   __ao2_weakproxy_find(c, arg, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Perform an ao2_find on a container with ao2_weakproxy objects, returning the real object. More...
 
#define ao2_wrlock(a)   __ao2_lock(a, AO2_LOCK_REQ_WRLOCK, __FILE__, __PRETTY_FUNCTION__, __LINE__, #a)
 
#define OBJ_KEY   OBJ_SEARCH_KEY
 
#define OBJ_PARTIAL_KEY   OBJ_SEARCH_PARTIAL_KEY
 
#define OBJ_POINTER   OBJ_SEARCH_OBJECT
 

Typedefs

typedef int( ao2_callback_data_fn) (void *obj, void *arg, void *data, int flags)
 Type of a generic callback function. More...
 
typedef int( ao2_callback_fn) (void *obj, void *arg, int flags)
 Type of a generic callback function. More...
 
typedef void(* ao2_destructor_fn) (void *vdoomed)
 Typedef for an object destructor. More...
 
typedef int( ao2_hash_fn) (const void *obj, int flags)
 
typedef int( ao2_sort_fn) (const void *obj_left, const void *obj_right, int flags)
 Type of generic container sort function. More...
 

Enumerations

enum  _cb_results { CMP_MATCH = 0x1, CMP_STOP = 0x2 }
 A callback function will return a combination of CMP_MATCH and CMP_STOP. The latter will terminate the search in a container. More...
 
enum  ao2_alloc_opts {
  AO2_ALLOC_OPT_LOCK_MUTEX = (0 << 0), AO2_ALLOC_OPT_LOCK_RWLOCK = (1 << 0), AO2_ALLOC_OPT_LOCK_NOLOCK = (2 << 0), AO2_ALLOC_OPT_LOCK_MASK = (3 << 0),
  AO2_ALLOC_OPT_LOCK_OBJ = AO2_ALLOC_OPT_LOCK_MASK, AO2_ALLOC_OPT_NO_REF_DEBUG = (1 << 2)
}
 Options available when allocating an ao2 object. More...
 
enum  ao2_container_opts {
  AO2_CONTAINER_ALLOC_OPT_INSERT_BEGIN = (1 << 0), AO2_CONTAINER_ALLOC_OPT_DUPS_MASK = (3 << 1), AO2_CONTAINER_ALLOC_OPT_DUPS_ALLOW = (0 << 1), AO2_CONTAINER_ALLOC_OPT_DUPS_REJECT = (1 << 1),
  AO2_CONTAINER_ALLOC_OPT_DUPS_OBJ_REJECT = (2 << 1), AO2_CONTAINER_ALLOC_OPT_DUPS_REPLACE = (3 << 1)
}
 Options available when allocating an ao2 container object. More...
 
enum  ao2_iterator_flags { AO2_ITERATOR_DONTLOCK = (1 << 0), AO2_ITERATOR_MALLOCD = (1 << 1), AO2_ITERATOR_UNLINK = (1 << 2), AO2_ITERATOR_DESCENDING = (1 << 3) }
 
enum  ao2_lock_req { AO2_LOCK_REQ_MUTEX, AO2_LOCK_REQ_RDLOCK, AO2_LOCK_REQ_WRLOCK }
 Which lock to request. More...
 
enum  search_flags {
  OBJ_UNLINK = (1 << 0), OBJ_NODATA = (1 << 1), OBJ_MULTIPLE = (1 << 2), OBJ_NOLOCK = (1 << 4),
  OBJ_SEARCH_MASK = (0x07 << 5), OBJ_SEARCH_NONE = (0 << 5), OBJ_SEARCH_OBJECT = (1 << 5), OBJ_SEARCH_KEY = (2 << 5),
  OBJ_SEARCH_PARTIAL_KEY = (4 << 5), OBJ_ORDER_MASK = (0x03 << 8), OBJ_ORDER_ASCENDING = (0 << 8), OBJ_ORDER_DESCENDING = (1 << 8),
  OBJ_ORDER_PRE = (2 << 8), OBJ_ORDER_POST = (3 << 8)
}
 Flags passed to ao2_callback_fn(), ao2_hash_fn(), and ao2_sort_fn() to modify behaviour. More...
 

Functions

void * __ao2_alloc_with_lockobj (size_t data_size, ao2_destructor_fn destructor_fn, void *lockobj, const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result
 
void * __ao2_callback_data (struct ao2_container *c, enum search_flags flags, ao2_callback_data_fn *cb_fn, void *arg, void *data, const char *tag, const char *file, int line, const char *func)
 
void __ao2_cleanup (void *obj)
 
void __ao2_cleanup_debug (void *obj, const char *tag, const char *file, int line, const char *function)
 
void * __ao2_find (struct ao2_container *c, const void *arg, enum search_flags flags, const char *tag, const char *file, int line, const char *func)
 
void * __ao2_global_obj_ref (struct ao2_global_obj *holder, const char *tag, const char *file, int line, const char *func, const char *name) attribute_warn_unused_result
 
void * __ao2_global_obj_replace (struct ao2_global_obj *holder, void *obj, const char *tag, const char *file, int line, const char *func, const char *name) attribute_warn_unused_result
 
int __ao2_global_obj_replace_unref (struct ao2_global_obj *holder, void *obj, const char *tag, const char *file, int line, const char *func, const char *name)
 
void * __ao2_iterator_next (struct ao2_iterator *iter, const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result
 
int __ao2_lock (void *a, enum ao2_lock_req lock_how, const char *file, const char *func, int line, const char *var)
 Lock an object. More...
 
int __ao2_trylock (void *a, enum ao2_lock_req lock_how, const char *file, const char *func, int line, const char *var)
 Try locking– (don't block if fail) More...
 
int __ao2_unlock (void *a, const char *file, const char *func, int line, const char *var)
 Unlock an object. More...
 
void * __ao2_weakproxy_find (struct ao2_container *c, const void *arg, enum search_flags flags, const char *tag, const char *file, int line, const char *func)
 
void ao2_iterator_cleanup (struct ao2_iterator *iter)
 
int ao2_iterator_count (struct ao2_iterator *iter)
 Get a count of the iterated container objects. More...
 
void ao2_iterator_destroy (struct ao2_iterator *iter)
 Destroy a container iterator. More...
 
struct ao2_iterator ao2_iterator_init (struct ao2_container *c, int flags) attribute_warn_unused_result
 Create an iterator for a container. More...
 
void ao2_iterator_restart (struct ao2_iterator *iter)
 Restart an iteration. More...
 
int ao2_match_by_addr (void *obj, void *arg, int flags)
 A common ao2_callback is one that matches by address. More...
 
void * ao2_object_get_lockaddr (void *obj)
 Return the mutex lock address of an object. More...
 
int ao2_ref_and_lock (void *obj)
 Increment reference count on an object and lock it. More...
 
int ao2_unlock_and_unref (void *obj)
 Unlock an object and decrement its reference count. More...
 
#define ao2_t_alloc_options(data_size, destructor_fn, options, debug_msg)   __ao2_alloc((data_size), (destructor_fn), (options), (debug_msg), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Allocate and initialize an object. More...
 
#define ao2_alloc_options(data_size, destructor_fn, options)   __ao2_alloc((data_size), (destructor_fn), (options), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_t_alloc(data_size, destructor_fn, debug_msg)   __ao2_alloc((data_size), (destructor_fn), AO2_ALLOC_OPT_LOCK_MUTEX, (debug_msg), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_alloc(data_size, destructor_fn)   __ao2_alloc((data_size), (destructor_fn), AO2_ALLOC_OPT_LOCK_MUTEX, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
void * __ao2_alloc (size_t data_size, ao2_destructor_fn destructor_fn, unsigned int options, const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result
 
#define ao2_ref(o, delta)    __ao2_ref((o), (delta), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Reference/unreference an object and return the old refcount. More...
 
#define ao2_t_ref(o, delta, tag)   __ao2_ref((o), (delta), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_bump(obj)   ao2_t_bump((obj), NULL)
 Bump refcount on an AO2 object by one, returning the object. More...
 
#define ao2_t_bump(obj, tag)
 
#define ao2_replace(dst, src)   ao2_t_replace((dst), (src), NULL)
 Replace one object reference with another cleaning up the original. More...
 
#define ao2_t_replace(dst, src, tag)
 
unsigned int ao2_options_get (void *obj)
 Retrieve the ao2 options used to create the object. More...
 
int __ao2_ref (void *o, int delta, const char *tag, const char *file, int line, const char *func)
 
#define AO2_WEAKPROXY()   struct ao2_weakproxy __weakproxy##__LINE__
 Macro which must be used at the beginning of weakproxy capable objects. More...
 
#define ao2_weakproxy_alloc(data_size, destructor_fn)   __ao2_weakproxy_alloc(data_size, destructor_fn, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Allocate an ao2_weakproxy object. More...
 
#define ao2_t_weakproxy_alloc(data_size, destructor_fn, tag)   __ao2_weakproxy_alloc(data_size, destructor_fn, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_weakproxy_set_object(weakproxy, obj, flags)   __ao2_weakproxy_set_object(weakproxy, obj, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Associate weakproxy with obj. More...
 
#define ao2_t_weakproxy_set_object(weakproxy, obj, flags, tag)   __ao2_weakproxy_set_object(weakproxy, obj, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_weakproxy_ref_object(weakproxy, delta, flags)   ao2_t_weakproxy_ref_object(weakproxy, delta, flags, NULL)
 Run ao2_t_ref on the object associated with weakproxy. More...
 
#define ao2_t_weakproxy_ref_object(weakproxy, delta, flags, tag)
 
#define ao2_weakproxy_get_object(weakproxy, flags)   __ao2_weakproxy_get_object(weakproxy, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Get the object associated with weakproxy. More...
 
#define ao2_t_weakproxy_get_object(weakproxy, flags, tag)   __ao2_weakproxy_get_object(weakproxy, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_get_weakproxy(obj)   __ao2_get_weakproxy(obj, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Get the weakproxy attached to obj. More...
 
#define ao2_t_get_weakproxy(obj, tag)   __ao2_get_weakproxy(obj, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
typedef void(* ao2_weakproxy_notification_cb) (void *weakproxy, void *data)
 
void * __ao2_weakproxy_alloc (size_t data_size, ao2_destructor_fn destructor_fn, const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result
 
int __ao2_weakproxy_set_object (void *weakproxy, void *obj, int flags, const char *tag, const char *file, int line, const char *func)
 
int __ao2_weakproxy_ref_object (void *weakproxy, int delta, int flags, const char *tag, const char *file, int line, const char *func)
 
void * __ao2_weakproxy_get_object (void *weakproxy, int flags, const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result
 
int ao2_weakproxy_subscribe (void *weakproxy, ao2_weakproxy_notification_cb cb, void *data, int flags)
 Request notification when weakproxy points to NULL. More...
 
int ao2_weakproxy_unsubscribe (void *weakproxy, ao2_weakproxy_notification_cb cb, void *data, int flags)
 Remove notification of real object destruction. More...
 
void * __ao2_get_weakproxy (void *obj, const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result
 

Object Containers

Here start declarations of containers.

#define ao2_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn)   __ao2_container_alloc_hash((ao2_options), (container_options), (n_buckets), (hash_fn), (sort_fn), (cmp_fn), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Allocate and initialize a hash container with the desired number of buckets. More...
 
#define ao2_t_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn, tag)   __ao2_container_alloc_hash((ao2_options), (container_options), (n_buckets), (hash_fn), (sort_fn), (cmp_fn), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_container_alloc_list(ao2_options, container_options, sort_fn, cmp_fn)   __ao2_container_alloc_list((ao2_options), (container_options), (sort_fn), (cmp_fn), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Allocate and initialize a list container. More...
 
#define ao2_t_container_alloc_list(ao2_options, container_options, sort_fn, cmp_fn, tag)   __ao2_container_alloc_list((ao2_options), (container_options), (sort_fn), (cmp_fn), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_container_alloc_rbtree(ao2_options, container_options, sort_fn, cmp_fn)   __ao2_container_alloc_rbtree((ao2_options), (container_options), (sort_fn), (cmp_fn), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Allocate and initialize a red-black tree container. More...
 
#define ao2_t_container_alloc_rbtree(ao2_options, container_options, sort_fn, cmp_fn, tag)   __ao2_container_alloc_rbtree((ao2_options), (container_options), (sort_fn), (cmp_fn), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_container_clone(orig, flags)   __ao2_container_clone(orig, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Create a clone/copy of the given container. More...
 
#define ao2_t_container_clone(orig, flags, tag)   __ao2_container_clone(orig, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
typedef void( ao2_prnt_fn) (void *where, const char *fmt,...)
 Print output. More...
 
typedef void( ao2_prnt_obj_fn) (void *v_obj, void *where, ao2_prnt_fn *prnt)
 Print object key. More...
 
struct ao2_container__ao2_container_alloc_hash (unsigned int ao2_options, unsigned int container_options, unsigned int n_buckets, ao2_hash_fn *hash_fn, ao2_sort_fn *sort_fn, ao2_callback_fn *cmp_fn, const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result
 
struct ao2_container__ao2_container_alloc_list (unsigned int ao2_options, unsigned int container_options, ao2_sort_fn *sort_fn, ao2_callback_fn *cmp_fn, const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result
 
struct ao2_container__ao2_container_alloc_rbtree (unsigned int ao2_options, unsigned int container_options, ao2_sort_fn *sort_fn, ao2_callback_fn *cmp_fn, const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result
 
int ao2_container_count (struct ao2_container *c)
 Returns the number of elements in a container. More...
 
int ao2_container_dup (struct ao2_container *dest, struct ao2_container *src, enum search_flags flags)
 Copy all object references in the src container into the dest container. More...
 
int ao2_container_dup_weakproxy_objs (struct ao2_container *dest, struct ao2_container *src, enum search_flags flags)
 Copy object references associated with src container weakproxies into the dest container. More...
 
struct ao2_container__ao2_container_clone (struct ao2_container *orig, enum search_flags flags, const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result
 
void ao2_container_dump (struct ao2_container *self, enum search_flags flags, const char *name, void *where, ao2_prnt_fn *prnt, ao2_prnt_obj_fn *prnt_obj)
 Display contents of the specified container. More...
 
void ao2_container_stats (struct ao2_container *self, enum search_flags flags, const char *name, void *where, ao2_prnt_fn *prnt)
 Display statistics of the specified container. More...
 
int ao2_container_check (struct ao2_container *self, enum search_flags flags)
 Perform an integrity check on the specified container. More...
 
int ao2_container_register (const char *name, struct ao2_container *self, ao2_prnt_obj_fn *prnt_obj)
 Register a container for CLI stats and integrity check. More...
 
void ao2_container_unregister (const char *name)
 Unregister a container for CLI stats and integrity check. More...
 

Object Management

Here we have functions to manage objects.

We can use the functions below on any kind of object defined by the user.

#define ao2_link(container, obj)   __ao2_link((container), (obj), 0, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Add an object to a container. More...
 
#define ao2_t_link(container, obj, tag)   __ao2_link((container), (obj), 0, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_link_flags(container, obj, flags)   __ao2_link((container), (obj), (flags), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Add an object to a container. More...
 
#define ao2_t_link_flags(container, obj, flags, tag)   __ao2_link((container), (obj), (flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_unlink(container, obj)   __ao2_unlink((container), (obj), 0, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Remove an object from a container. More...
 
#define ao2_t_unlink(container, obj, tag)   __ao2_unlink((container), (obj), 0, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_unlink_flags(container, obj, flags)   __ao2_unlink((container), (obj), (flags), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Remove an object from a container. More...
 
#define ao2_t_unlink_flags(container, obj, flags, tag)   __ao2_unlink((container), (obj), (flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
int __ao2_link (struct ao2_container *c, void *obj_new, int flags, const char *tag, const char *file, int line, const char *func)
 
void * __ao2_unlink (struct ao2_container *c, void *obj, int flags, const char *tag, const char *file, int line, const char *func)
 
#define ao2_callback(c, flags, cb_fn, arg)   __ao2_callback((c), (flags), (cb_fn), (arg), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below. More...
 
#define ao2_t_callback(c, flags, cb_fn, arg, tag)   __ao2_callback((c), (flags), (cb_fn), (arg), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
void * __ao2_callback (struct ao2_container *c, enum search_flags flags, ao2_callback_fn *cb_fn, void *arg, const char *tag, const char *file, int line, const char *func)
 

Detailed Description

Object Model implementing objects and containers.

Definition in file astobj2.h.

Macro Definition Documentation

#define ao2_alloc_with_lockobj (   data_size,
  destructor_fn,
  lockobj,
  tag 
)    __ao2_alloc_with_lockobj((data_size), (destructor_fn), (lockobj), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)

Allocate and initialize an object with separate locking.

Since
14.1.0
Parameters
data_sizeThe sizeof() of the user-defined structure.
destructor_fnThe destructor function (can be NULL)
lockobjA separate ao2 object that will provide locking.
tagAn ao2 object debug tracing message.
Returns
A pointer to user-data.
See also
ao2_alloc for additional details.
Note
lockobj must be a valid AO2 object.

Definition at line 431 of file astobj2.h.

Referenced by ast_sorcery_lockable_alloc().

#define ao2_bump (   obj)    ao2_t_bump((obj), NULL)

Bump refcount on an AO2 object by one, returning the object.

Since
12 This is useful for inlining a ref bump, and you don't care about the ref count. Also NULL safe, for even more convenience.
Parameters
objAO2 object to bump the refcount on.
Returns
The given obj pointer.

Definition at line 480 of file astobj2.h.

Referenced by __ast_frisolate(), __ast_sorcery_object_type_insert_wizard(), app_create(), app_send(), ast_aeap_send_msg_tsx(), ast_ari_bridges_set_video_source(), ast_ari_channels_create(), ast_bridge_blob_create_from_snapshots(), ast_bridge_channel_get_chan(), ast_bridge_get_snapshot(), ast_bridge_get_snapshot_by_uniqueid(), ast_bridges(), ast_cdr_get_config(), ast_cdr_message_router(), ast_cel_set_config(), ast_channel_blob_create(), ast_channel_cache_by_name(), ast_channel_snapshot_create(), ast_channel_start_silence_generator(), ast_channel_yank(), ast_dns_query_set_resolve_async(), ast_dns_resolve_recurring(), ast_dns_resolver_set_data(), ast_format_attribute_set(), ast_format_create_named(), ast_format_get_codec(), ast_format_joint(), ast_format_parse_sdp_fmtp(), ast_local_lock_all(), ast_openvstream(), ast_rtp_bundle(), ast_rtp_codecs_get_payload(), ast_rtp_codecs_get_payload_format(), ast_rtp_codecs_get_preferred_format(), ast_rtp_codecs_payloads_set_m_type(), ast_rtp_new(), ast_sip_dialog_get_endpoint(), ast_sip_get_distributor_serializer(), ast_sip_schedule_task(), ast_sip_transport_monitor_register_replace_key(), ast_slinfactory_init(), ast_slinfactory_init_with_format(), ast_sorcery_get_wizard_mapping(), ast_speech_new(), ast_stream_set_formats(), ast_unreal_indicate(), attended_transfer_bridge(), begin_dial_prerun(), chan_pjsip_answer(), chan_pjsip_indicate(), channel_do_masquerade(), command_prestart_get_container(), conf_set_menu_to_user(), control_create(), control_set_app(), dial_transfer(), dns_query_alloc(), dns_query_recurring_resolution_callback(), dns_system_resolver_resolve(), filter_history(), generic_fax_exec(), get_dial_bridge(), make_silence(), newpvt(), pjsip_acf_channel_read(), prometheus_general_config_get(), ring_entry(), set_read_to_slin(), softmix_bridge_stream_topology_changed(), speech_background(), stasis_app_control_play_uri(), stasis_app_control_record(), stasis_app_exec(), stasis_cache_get_by_eid(), stasis_forward_all(), stasis_message_router_publish_sync(), stasis_state_subscriber_data(), stasis_unsubscribe(), and wrap_hook().

#define ao2_callback (   c,
  flags,
  cb_fn,
  arg 
)    __ao2_callback((c), (flags), (cb_fn), (arg), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)

ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below.

Parameters
cA pointer to the container to operate on.
flagsA set of flags specifying the operation to perform, partially used by the container code, but also passed to the callback.
  • If OBJ_NODATA is set, ao2_callback will return NULL. No refcounts of any of the traversed objects will be incremented. On the converse, if it is NOT set (the default), the ref count of the first matching object will be incremented and returned.
  • If OBJ_MULTIPLE is set, the ref count of all matching objects will be incremented in an iterator for a temporary container and returned.
  • If OBJ_SEARCH_OBJECT is set, the traversed items will be restricted to the objects in the bucket that the object key hashes to.
  • If OBJ_SEARCH_KEY is set, the traversed items will be restricted to the objects in the bucket that the object key hashes to.
cb_fnA function pointer, that will be called on all objects, to see if they match. This function returns CMP_MATCH if the object is matches the criteria; CMP_STOP if the traversal should immediately stop, or both (via bitwise ORing), if you find a match and want to end the traversal, and 0 if the object is not a match, but the traversal should continue. This is the function that is applied to each object traversed. Its arguments are: (void *obj, void *arg, int flags), where: obj is an object arg is the same as arg passed into ao2_callback flags is the same as flags passed into ao2_callback (flags are also used by ao2_callback).
argpassed to the callback.
Return values
NULLon failure or no matching object found.
Returns
object found if OBJ_MULTIPLE is not set in the flags parameter.
ao2_iterator pointer if OBJ_MULTIPLE is set in the flags parameter. The iterator must be destroyed with ao2_iterator_destroy() when the caller no longer needs it.

If the function returns any objects, their refcount is incremented, and the caller is in charge of decrementing them once done.

Typically, ao2_callback() is used for two purposes:

  • to perform some action (including removal from the container) on one or more objects; in this case, cb_fn() can modify the object itself, and to perform deletion should set CMP_MATCH on the matching objects, and have OBJ_UNLINK set in flags.
  • to look for a specific object in a container; in this case, cb_fn() should not modify the object, but just return a combination of CMP_MATCH and CMP_STOP on the desired object. Other usages are also possible, of course.

This function searches through a container and performs operations on objects according on flags passed. XXX describe better The comparison is done calling the compare function set implicitly. The arg pointer can be a pointer to an object or to a key, we can say this looking at flags value. If arg points to an object we will search for the object pointed by this value, otherwise we search for a key value. If the key is not unique we only find the first matching value.

The use of flags argument is the follow:

 OBJ_UNLINK              unlinks the object found
 OBJ_NODATA              on match, do not return an object
                         Callbacks use OBJ_NODATA as a default
                         functions such as find() do
 OBJ_MULTIPLE            return multiple matches
                         Default is no.
 OBJ_SEARCH_OBJECT       the pointer is to an object
 OBJ_SEARCH_KEY          the pointer is to a search key
 OBJ_SEARCH_PARTIAL_KEY  the pointer is to a partial search key
Note
When the returned object is no longer in use, ao2_ref() should be used to free the additional reference possibly created by this function.

Definition at line 1693 of file astobj2.h.

Referenced by admin_exec(), ao2_container_dup(), ao2_container_dup_weakproxy_objs(), ast_ari_applications_list(), ast_ari_websocket_events_event_websocket_dtor(), ast_bridge_features_merge(), ast_bucket_file_metadata_callback(), ast_calendar_clear_events(), ast_calendar_merge_events(), ast_calendar_unregister(), ast_cdr_setvar(), ast_channel_dialed_causes_channels(), ast_channel_dialed_causes_clear(), ast_codec_get_by_id(), ast_extension_state_del(), ast_media_get_media(), ast_media_get_variants(), ast_merge_contexts_and_delete(), ast_multi_channel_blob_get_channels(), ast_namedgroups_intersect(), ast_odbc_get_max_connections(), ast_sip_transport_monitor_unregister_all(), ast_softhangup_all(), ast_sorcery_force_reload(), ast_sorcery_global_observer_remove(), ast_sorcery_instance_observer_remove(), ast_sorcery_is_object_field_registered(), ast_sorcery_load(), ast_sorcery_observer_remove(), ast_sorcery_reload(), ast_sorcery_wizard_observer_remove(), ast_unregister_indication_country(), channel_admin_exec(), cleanup(), context_table_create_autohints(), create_sound_blob(), handle_cli_sounds_show(), load_config(), load_indications(), load_module(), object_type_loaded_observer(), one_protocol(), parking_lot_inspect_parked_user(), parking_lot_retrieve_parked_user(), parse_config(), process_config(), reload_queues(), reload_single_queue(), set_config(), sorcery_observers_notify_create(), sorcery_observers_notify_delete(), sorcery_observers_notify_loaded(), sorcery_observers_notify_update(), stasis_app_get_all(), stasis_app_to_cli(), stasis_cache_dump_all(), stasis_cache_dump_by_eid(), unload_module(), xmpp_client_service_discovery_result_hook(), xmpp_init_event_distribution(), xmpp_pak_presence(), and xmpp_roster_hook().

#define ao2_container_alloc_hash (   ao2_options,
  container_options,
  n_buckets,
  hash_fn,
  sort_fn,
  cmp_fn 
)    __ao2_container_alloc_hash((ao2_options), (container_options), (n_buckets), (hash_fn), (sort_fn), (cmp_fn), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Allocate and initialize a hash container with the desired number of buckets.

We allocate space for a struct astobj_container, struct container and the buckets[] array.

Parameters
ao2_optionsContainer ao2 object options (See enum ao2_alloc_opts)
container_optionsContainer behaviour options (See enum ao2_container_opts)
n_bucketsNumber of buckets for hash
hash_fnPointer to a function computing a hash value. (NULL if everyting goes in first bucket.)
sort_fnPointer to a sort function. (NULL to not sort the buckets.)
cmp_fnPointer to a compare function used by ao2_find. (NULL to match everything)
Returns
A pointer to a struct container.
Note
Destructor is set implicitly.
Examples:
app_skel.c.

Definition at line 1303 of file astobj2.h.

Referenced by aco_option_container_alloc(), ast_aeap_create(), ast_ari_websocket_events_event_websocket_init(), ast_bridge_peers_nolock(), ast_bucket_init(), ast_calendar_event_container_alloc(), ast_channels_init(), ast_codec_init(), ast_config_hook_register(), ast_config_text_file_save2(), ast_datastores_alloc(), ast_endpoint_init(), ast_format_cache_init(), ast_format_init(), ast_get_namedgroups(), ast_media_cache_init(), ast_media_index_create(), ast_multi_channel_blob_create(), ast_multi_channel_blob_get_channels(), ast_named_locks_init(), ast_pbx_init(), ast_sip_initialize_scheduler(), ast_sorcery_init(), ast_stasis_channels_init(), ast_str_container_alloc_options(), ast_tps_init(), ast_xmldoc_build_documentation(), ast_xmpp_client_config_alloc(), bucket_file_alloc(), build_calendar(), init_queue(), jingle_config_alloc(), jingle_endpoint_state_create(), load_module(), named_acl_config_alloc(), parking_config_alloc(), realtime_sqlite3_require(), sig_pri_load(), skel_config_alloc(), sorcery_object_type_alloc(), stasis_cache_create_full(), stasis_init(), stasis_state_manager_create(), stasis_topic_pool_create(), test_performance(), xml_translate(), xmpp_client_alloc(), and xmpp_client_create_buddy().

#define ao2_container_alloc_list (   ao2_options,
  container_options,
  sort_fn,
  cmp_fn 
)    __ao2_container_alloc_list((ao2_options), (container_options), (sort_fn), (cmp_fn), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Allocate and initialize a list container.

Parameters
ao2_optionsContainer ao2 object options (See enum ao2_alloc_opts)
container_optionsContainer behaviour options (See enum ao2_container_opts)
sort_fnPointer to a sort function. (NULL if list not sorted.)
cmp_fnPointer to a compare function used by ao2_find. (NULL to match everything)
Returns
A pointer to a struct container.
Note
Destructor is set implicitly.
Implemented as a degenerate hash table.
Examples:
app_skel.c.

Definition at line 1327 of file astobj2.h.

Referenced by __ast_sorcery_wizard_register(), ast_add_hint(), ast_bridge_features_init(), ast_local_init(), ast_msg_alloc(), ast_pbx_init(), ast_pickup_find_by_group(), ast_refer_alloc(), ast_rtp_ice_add_cand(), ast_rtp_ice_add_remote_candidate(), ast_sorcery_init(), ast_sorcery_retrieve_by_fields(), ast_sorcery_retrieve_by_prefix(), ast_sorcery_retrieve_by_regex(), build_conf(), build_mansession(), command_prestart_queue_command(), control_create(), init_queue(), load_module(), load_modules(), object_type_loaded_observer(), sorcery_object_type_alloc(), stasis_cache_dump_all(), stasis_cache_dump_by_eid(), stasis_cache_get_all(), test_performance(), and xmpp_config_alloc().

#define ao2_container_alloc_rbtree (   ao2_options,
  container_options,
  sort_fn,
  cmp_fn 
)    __ao2_container_alloc_rbtree((ao2_options), (container_options), (sort_fn), (cmp_fn), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Allocate and initialize a red-black tree container.

Parameters
ao2_optionsContainer ao2 object options (See enum ao2_alloc_opts)
container_optionsContainer behaviour options (See enum ao2_container_opts)
sort_fnPointer to a sort function.
cmp_fnPointer to a compare function used by ao2_find. (NULL to match everything)
Returns
A pointer to a struct container.
Note
Destructor is set implicitly.

Definition at line 1349 of file astobj2.h.

Referenced by __queues_show(), app_create(), ast_bridging_init(), bucket_alloc(), conf_alloc(), handle_cli_sounds_show(), and test_performance().

#define ao2_container_clone (   orig,
  flags 
)    __ao2_container_clone(orig, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Create a clone/copy of the given container.

Since
11.0
Parameters
origContainer to copy all object references from.
flagsOBJ_NOLOCK if a lock is already held on the container.
Note
This can potentially be expensive because a malloc is needed for every object in the orig container.
Returns
Clone container on success.
Return values
NULLon error.

Definition at line 1419 of file astobj2.h.

Referenced by ast_bucket_file_copy().

#define AO2_FIELD_HASH_FN (   stype,
  field,
  hash_fn 
)

Creates a hash function for a structure field.

Parameters
stypeThe structure type
fieldThe string field in the structure to hash
hash_fnFunction which hashes the field

AO2_FIELD_HASH_FN(mystruct, myfield, ast_str_hash) will produce a function named mystruct_hash_fn which hashes mystruct->myfield with ast_str_hash.

Definition at line 1957 of file astobj2.h.

#define ao2_get_weakproxy (   obj)    __ao2_get_weakproxy(obj, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Get the weakproxy attached to obj.

Since
14.0.0
Parameters
objThe object to retrieve a weakproxy from
Returns
The weakproxy object

Definition at line 688 of file astobj2.h.

#define ao2_global_obj_ref (   holder)    __ao2_global_obj_ref(&holder, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)

Get a reference to the object stored in the global holder.

Since
11.0
Parameters
holderGlobal ao2 object holder.
Returns
Reference to current ao2 object stored in the holder.
Return values
NULLif no object available.
Examples:
app_skel.c.

Definition at line 918 of file astobj2.h.

Referenced by __ast_manager_event_multichan(), __ast_vm_greeter_register(), __ast_vm_register(), ast_ari_config_get(), ast_cdr_engine_term(), ast_cdr_get_config(), ast_cdr_set_config(), ast_cel_backend_register(), ast_cel_backend_unregister(), ast_cel_check_enabled(), ast_cel_fabricate_channel_from_event(), ast_cel_get_config(), ast_cel_set_config(), ast_named_acl_find(), ast_parking_blind_transfer_park(), ast_parking_is_exten_park(), ast_parking_park_bridge_channel(), ast_parking_park_call(), ast_parking_provider_registered(), ast_parking_register_bridge_features(), ast_parking_unregister_bridge_features(), ast_sip_transport_monitor_register_replace_key(), ast_sip_transport_monitor_unregister_all(), ast_sip_transport_monitor_unregister_key(), ast_smdi_interface_find(), ast_vm_greeter_is_registered(), ast_vm_greeter_unregister(), ast_vm_is_registered(), ast_vm_unregister(), ast_xmpp_client_find(), astman_verify_session_readpermissions(), astman_verify_session_writepermissions(), build_mansession(), cdr_toggle_runtime_options(), conf_find_bridge_profile(), conf_find_user_profile(), conf_set_menu_to_user(), find_session(), find_session_by_nonce(), function_amiclient(), handle_channel_snapshot_update_message(), handle_kickmanconn(), handle_show_named_acl_cmd(), handle_showmanconn(), hep_queue_cb(), hepv3_config_post_apply(), hepv3_get_uuid_type(), hepv3_is_loaded(), hepv3_send_packet(), jingle_endpoint_state_find_or_create(), jingle_request(), parking_dynamic_lots_enabled(), prometheus_config_post_apply(), prometheus_general_config_get(), prometheus_general_config_set(), purge_sessions(), skel_find_or_create_state(), stasis_init(), stasis_message_type_declined(), transport_state_callback(), xmpp_action_hook(), xmpp_cli_create_collection(), xmpp_cli_create_leafnode(), xmpp_cli_delete_pubsub_node(), xmpp_cli_list_pubsub_nodes(), xmpp_cli_purge_pubsub_nodes(), xmpp_client_find_or_create(), xmpp_client_reconnect(), xmpp_client_send_message(), xmpp_client_set_presence(), xmpp_client_thread(), xmpp_component_register_get_hook(), xmpp_component_service_discovery_get_hook(), xmpp_component_service_discovery_items_hook(), xmpp_connect_hook(), xmpp_init_event_distribution(), xmpp_join_exec(), xmpp_leave_exec(), xmpp_log_hook(), xmpp_pubsub_build_publish_skeleton(), xmpp_pubsub_iq_create(), xmpp_pubsub_publish_device_state(), xmpp_pubsub_subscribe(), xmpp_roster_hook(), and xmpp_sendgroup_exec().

#define ao2_global_obj_release (   holder)    __ao2_global_obj_replace_unref(&holder, NULL, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)

Release the ao2 object held in the global holder.

Since
11.0
Parameters
holderGlobal ao2 object holder.
Examples:
app_skel.c.

Definition at line 859 of file astobj2.h.

Referenced by ast_ari_config_destroy(), ast_parking_unregister_bridge_features(), ast_vm_greeter_unregister(), ast_vm_unregister(), bridge_agent_hold_dissolving(), conf_destroy_config(), load_module(), sorcery_config_destructor(), stasis_cleanup(), and unload_module().

#define ao2_global_obj_replace (   holder,
  obj 
)    __ao2_global_obj_replace(&holder, (obj), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)

Replace an ao2 object in the global holder.

Since
11.0
Parameters
holderGlobal ao2 object holder.
objObject to put into the holder. Can be NULL.
Note
This function automatically increases the reference count to account for the reference that the global holder now holds to the object.
Returns
Reference to previous global ao2 object stored.
Return values
NULLif no object available.

Definition at line 878 of file astobj2.h.

#define ao2_global_obj_replace_unref (   holder,
  obj 
)    __ao2_global_obj_replace_unref(&holder, (obj), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)

Replace an ao2 object in the global holder, throwing away any old object.

Since
11.0
Parameters
holderGlobal ao2 object holder.
objObject to put into the holder. Can be NULL.
Note
This function automatically increases the reference count to account for the reference that the global holder now holds to the object. It also decreases the reference count of any object being replaced.
Return values
0The global object was previously empty
1The global object was not previously empty

Definition at line 901 of file astobj2.h.

Referenced by __ast_vm_greeter_register(), __ast_vm_register(), ast_parking_register_bridge_features(), hepv3_config_post_apply(), and stasis_init().

#define AO2_GLOBAL_OBJ_STATIC (   name)
Value:
struct ao2_global_obj name = { \
.lock = AST_RWLOCK_INIT_VALUE, \
}

Define a global object holder to be used to hold an ao2 object, statically initialized.

Since
11.0
Parameters
nameThis will be the name of the object holder.

This macro creates a global object holder that can be used to hold an ao2 object accessible using the API. The structure is allocated and initialized to be empty.

Example usage:

1 static AO2_GLOBAL_OBJ_STATIC(global_cfg);

This defines global_cfg, intended to hold an ao2 object accessible using an API.

Definition at line 847 of file astobj2.h.

#define ao2_link (   container,
  obj 
)    __ao2_link((container), (obj), 0, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Add an object to a container.

Parameters
containerThe container to operate on.
objThe object to be added.
Return values
0on errors.
1on success.

This function inserts an object in a container according its key.

Note
Remember to set the key before calling this function.
This function automatically increases the reference count to account for the reference that the container now holds to the object.
Examples:
app_skel.c.

Definition at line 1532 of file astobj2.h.

Referenced by __ast_sorcery_object_field_register(), __ast_sorcery_object_type_insert_wizard(), add_column_name(), alloc_variant(), ast_add_hint(), ast_aeap_user_data_register(), ast_bridge_dtmf_hook(), ast_bridge_peers_nolock(), ast_bucket_file_metadata_set(), ast_cel_backend_register(), ast_change_hint(), ast_change_name(), ast_channel_dialed_causes_add(), ast_config_hook_register(), ast_datastores_add(), ast_get_namedgroups(), ast_merge_contexts_and_delete(), ast_multi_channel_blob_add_channel(), ast_multi_channel_blob_get_channels(), ast_register_indication_country(), ast_rtp_ice_add_cand(), ast_rtp_ice_add_remote_candidate(), ast_sip_schedule_task(), ast_sorcery_global_observer_add(), ast_sorcery_instance_observer_add(), ast_sorcery_object_fields_register(), ast_sorcery_observer_add(), ast_sorcery_wizard_observer_add(), ast_str_container_add(), ast_xmldoc_build_documentation(), bridge_register(), build_calendar(), build_mansession(), build_profile(), build_route(), chan_pjsip_add_hold(), channel_do_masquerade(), command_prestart_queue_command(), context_table_create_autohints(), event_session_alloc(), fax_session_new(), find_channel_by_group(), handle_channel_snapshot_update_message(), jingle_action_session_initiate(), jingle_request(), join_conference_bridge(), load_config(), local_request_with_stream_topology(), merge_container_cb(), parking_lot_build_or_update(), parse_config(), realtime_peer(), realtime_user(), reload_single_member(), set_config(), sorcery_astdb_retrieve_fields_common(), stasis_app_bridge_playback_channel_add(), stasis_app_control_play_uri(), stasis_app_control_record(), stasis_app_exec(), test_performance(), transport_state_callback(), xml_translate(), and xmpp_client_create_buddy().

#define ao2_link_flags (   container,
  obj,
  flags 
)    __ao2_link((container), (obj), (flags), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Add an object to a container.

Parameters
containerThe container to operate on.
objThe object to be added.
flagssearch_flags to control linking the object. (OBJ_NOLOCK)
Return values
0on errors.
1on success.

This function inserts an object in a container according its key.

Note
Remember to set the key before calling this function.
This function automatically increases the reference count to account for the reference that the container now holds to the object.

Definition at line 1554 of file astobj2.h.

Referenced by __ast_bucket_scheme_register(), __ast_channel_alloc_ap(), __ast_format_interface_register(), __ast_sorcery_wizard_register(), app_subscribe_bridge(), app_subscribe_channel(), app_subscribe_endpoint(), ast_channel_publish_snapshot(), ast_format_cache_set(), ast_media_cache_create_or_update(), ast_media_cache_retrieve(), ast_sip_dialog_set_endpoint(), ast_sip_dialog_set_serializer(), create_dsn(), dup_weakproxy_cb(), publish_cluster_discovery_to_stasis(), stasis_topic_pool_get_topic(), and xmpp_pak_presence().

#define ao2_ref (   o,
  delta 
)    __ao2_ref((o), (delta), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Reference/unreference an object and return the old refcount.

Parameters
oA pointer to the object
deltaValue to add to the reference counter.
Returns
The value of the reference counter before the operation.

Increase/decrease the reference counter according the value of delta.

If the refcount goes to zero, the object is destroyed.

Note
The object must not be locked by the caller of this function, as it is invalid to try to unlock it after releasing the reference.
if we know the pointer to an object, it is because we have a reference count to it, so the only case when the object can go away is when we release our reference, and it is the last one in existence.
Examples:
app_skel.c.

Definition at line 459 of file astobj2.h.

Referenced by __aco_option_register(), __ao2_cleanup(), __ast_channel_alloc_ap(), __ast_format_interface_register(), __ast_read(), __find_callno(), __queues_show(), __rtp_recvfrom(), __rtp_sendto(), acf_faxopt_read(), acf_faxopt_write(), aco_option_register_deprecated(), aco_process_var(), aco_set_defaults(), action_coreshowchannelmap(), action_coreshowchannels(), add_column_name(), add_format_information_cb(), add_hintdevice(), add_ice_to_stream(), add_to_dial_bridge(), add_to_queue(), admin_exec(), agent_request_exec(), alias_show(), alloc_variant(), ao2_iterator_restart(), ao2_ref_and_lock(), app_create(), app_subscribe_bridge(), app_subscribe_channel(), app_subscribe_endpoint(), app_to_json(), ast_add_hint(), ast_aeap_create(), ast_aeap_create_and_connect(), ast_aeap_custom_fields_get(), ast_aeap_message_create1(), ast_aeap_message_create2(), ast_aeap_message_create_error(), ast_aeap_message_create_request(), ast_aeap_message_deserialize(), ast_aeap_send_msg(), ast_aeap_send_msg_tsx(), ast_aeap_user_data_object_by_id(), ast_aeap_user_data_register(), ast_ari_add_handler(), ast_ari_applications_filter(), ast_ari_asterisk_update_object(), ast_ari_bridges_clear_video_source(), ast_ari_bridges_list(), ast_ari_bridges_set_video_source(), ast_ari_channels_create(), ast_ari_channels_get(), ast_ari_channels_list(), ast_ari_config_validate_user(), ast_ari_endpoints_list(), ast_ari_endpoints_list_by_tech(), ast_ari_endpoints_refer_to_endpoint(), ast_ari_endpoints_send_message_to_endpoint(), ast_ari_websocket_events_event_websocket_established(), ast_ari_websocket_session_create(), ast_bridge_blob_create(), ast_bridge_blob_create_from_snapshots(), ast_bridge_channel_feature_digit(), ast_bridge_channel_kick(), ast_bridge_channel_lock_bridge(), ast_bridge_channel_merge_inhibit(), ast_bridge_channel_write_unhold(), ast_bridge_depart(), ast_bridge_destroy(), ast_bridge_dtmf_hook(), ast_bridge_features_cleanup(), ast_bridge_get_snapshot_by_uniqueid(), ast_bridge_interval_hook(), ast_bridge_join(), ast_bridge_notify_masquerade(), ast_bridge_publish_attended_transfer(), ast_bridge_publish_enter(), ast_bridge_publish_leave(), ast_bridge_publish_merge(), ast_bridge_publish_state(), ast_bridge_snapshot_create(), ast_bridge_transfer_acquire_bridge(), ast_bucket_alloc(), ast_bucket_file_alloc(), ast_bucket_file_copy(), ast_bucket_file_json(), ast_bucket_json(), ast_calendar_unref_event(), ast_cdr_fork(), ast_cel_backend_register(), ast_cel_backend_unregister(), ast_cel_general_config_alloc(), ast_cel_get_config(), ast_cel_set_config(), ast_change_hint(), ast_channel_bridge_peer(), ast_channel_dialed_causes_add(), ast_channel_get_bridge(), ast_channel_get_bridge_channel(), ast_channel_get_vars(), ast_channel_publish_blob(), ast_channel_publish_cached_blob(), ast_channel_publish_final_snapshot(), ast_channel_publish_snapshot(), ast_channel_snapshot_create(), ast_channel_suppress(), ast_closestream(), ast_codec_samples_count(), ast_complete_channels(), ast_config_hook_register(), ast_config_text_file_save2(), ast_datastores_alloc_datastore(), ast_dns_query_set_add(), ast_dns_query_set_create(), ast_dns_query_set_resolve_async(), ast_dns_resolve(), ast_dns_resolve_async(), ast_dns_resolve_recurring(), ast_dns_resolve_recurring_cancel(), ast_endpoint_blob_create(), ast_endpoint_blob_publish(), ast_endpoint_latest_snapshot(), ast_endpoint_shutdown(), ast_extension_state_del(), ast_extension_state_extended(), ast_format_attribute_get(), ast_format_attribute_set(), ast_format_cache_get_by_codec(), ast_format_cap_append_by_type(), ast_format_cap_get_best_by_type(), ast_format_cap_get_compatible(), ast_format_cap_get_format(), ast_format_cap_remove_by_type(), ast_format_clone(), ast_format_create_named(), ast_format_generate_sdp_fmtp(), ast_format_parse_sdp_fmtp(), ast_get_namedgroups(), ast_hangup(), ast_iax2_new(), ast_local_get_peer(), ast_local_setup_bridge(), ast_local_setup_masquerade(), ast_local_unlock_all(), ast_manager_event_blob_create(), ast_media_cache_create_or_update(), ast_media_cache_delete(), ast_media_cache_exists(), ast_media_cache_retrieve(), ast_media_cache_retrieve_metadata(), ast_media_get_media(), ast_media_get_variants(), ast_media_index_create(), ast_merge_contexts_and_delete(), ast_msg_alloc(), ast_msg_destroy(), ast_msg_get_var(), ast_msg_queue(), ast_msg_ref(), ast_msg_send(), ast_multi_channel_blob_add_channel(), ast_multi_channel_blob_create(), ast_multi_channel_blob_get_channel(), ast_multi_channel_blob_get_channels(), ast_multi_object_blob_create(), ast_multi_object_blob_single_channel_publish(), ast_mwi_blob_create(), ast_mwi_mailbox_delete_all(), ast_mwi_mailbox_delete_by_regex(), ast_mwi_publish(), ast_mwi_publish_by_mailbox(), ast_odbc_get_max_connections(), ast_odbc_release_obj(), ast_openstream_full(), ast_openvstream(), ast_parked_call_payload_create(), ast_pickup_find_by_group(), ast_print_namedgroups(), ast_query_set_resolve(), ast_refer_alloc(), ast_refer_destroy(), ast_refer_get_var(), ast_refer_get_var_and_unlink(), ast_refer_ref(), ast_refer_send(), ast_remove_hint(), ast_rtcp_write(), ast_rtp_bundle(), ast_rtp_codecs_payload_replace_format(), ast_rtp_codecs_payloads_set_m_type(), ast_rtp_codecs_payloads_set_rtpmap_type_rate(), ast_rtp_codecs_payloads_unset(), ast_rtp_destroy(), ast_rtp_engine_unload_format(), ast_rtp_ice_add_cand(), ast_rtp_ice_add_remote_candidate(), ast_rtp_ice_get_local_candidates(), ast_rtp_ice_start(), ast_rtp_ice_stop(), ast_rtp_ice_turn_request(), ast_rtp_instance_make_compatible(), ast_rtp_instance_new(), ast_rtp_lookup_mime_multiple2(), ast_rtp_prop_set(), ast_rtp_publish_rtcp_message(), ast_rtp_stop(), ast_sip_dialog_get_endpoint(), ast_sip_dialog_set_endpoint(), ast_sip_dialog_set_serializer(), ast_sip_sched_is_task_running_by_name(), ast_sip_sched_task_cancel_by_name(), ast_sip_sched_task_get_next_run_by_name(), ast_sip_sched_task_get_times_by_name2(), ast_sip_schedule_task(), ast_sip_transport_monitor_register_replace_key(), ast_sip_transport_monitor_unregister_all(), ast_sip_transport_monitor_unregister_key(), ast_smdi_interface_find(), ast_sorcery_alloc(), ast_sorcery_global_observer_add(), ast_sorcery_instance_observer_add(), ast_sorcery_object_set_congestion_levels(), ast_sorcery_objectset_create2(), ast_sorcery_objectset_json_create(), ast_sorcery_observer_add(), ast_sorcery_ref(), ast_sorcery_retrieve_by_id(), ast_sorcery_wizard_observer_add(), ast_sorcery_wizard_unregister(), ast_sounds_get_index_for_file(), ast_speech_destroy(), ast_speech_new(), ast_str_container_add(), ast_stream_create_resolved(), ast_stream_topology_alloc(), ast_stream_topology_create_from_format_cap(), ast_system_publish_registry(), ast_taskprocessor_get(), ast_taskprocessor_listener_get_tps(), ast_taskprocessor_unreference(), ast_tcptls_client_start_timeout(), ast_tone_zone_ref(), ast_tone_zone_sound_ref(), ast_tone_zone_sound_unref(), ast_tone_zone_unref(), ast_tps_init(), ast_translate_available_formats(), ast_translator_best_choice(), ast_unreal_alloc_stream_topology(), ast_unreal_answer(), ast_unreal_channel_push_to_bridge(), ast_unreal_digit_begin(), ast_unreal_digit_end(), ast_unreal_hangup(), ast_unreal_indicate(), ast_unreal_new_channels(), ast_unreal_sendhtml(), ast_unreal_sendtext(), ast_unreal_setoption(), ast_unreal_write_stream(), ast_xmpp_client_config_alloc(), ast_xmpp_client_find(), ast_xmpp_client_unref(), astman_verify_session_readpermissions(), astman_verify_session_writepermissions(), attended_transfer_bridge(), attended_transfer_properties_alloc(), audiosocket_request(), bridge_agent_hold_push(), bridge_app_subscribed(), bridge_app_subscribed_involved(), bridge_base_init(), bridge_basic_change_personality(), bridge_channel_ind_thread(), bridge_merge_message_create(), bridge_show_specific_print_channel(), bucket_alloc(), bucket_file_alloc(), build_conf(), build_mansession(), chan_pjsip_answer(), chan_pjsip_call(), chan_pjsip_devicestate(), chan_pjsip_get_rtp_peer(), chan_pjsip_get_vrtp_peer(), chan_pjsip_indicate(), chan_pjsip_new(), chan_pjsip_read_stream(), chan_pjsip_sendtext_data(), chan_pjsip_set_rtp_peer(), chan_rtp_get_rtp_peer(), channel_admin_exec(), channel_do_masquerade(), channel_state_invalid(), clear_history_entry_cb(), cli_alias_passthrough(), cli_complete_show(), cli_fax_show_session(), cli_fax_show_sessions(), compatible_formats_exist(), complete_core_show_hint(), conf_alloc(), conf_announce_channel_push(), conf_bridge_profile_copy(), conf_bridge_profile_destroy(), conf_find_bridge_profile(), conf_find_user_profile(), conf_free(), conf_send_event_to_participants(), console_new(), context_table_create_autohints(), control_create(), control_dispatch_all(), control_flush_queue(), coreshowchannelmap_add_connected_channels(), create_dsn(), create_object(), create_outgoing_sdp_stream(), create_rtp(), destroy_gateway(), destroy_queue(), destroy_session(), destroy_v21_sessions(), device_state_cb(), dial_exec_full(), dns_query_alloc(), dns_query_recurring_resolution_callback(), dns_query_recurring_scheduled_callback(), dns_query_set_callback(), dns_query_set_destroy(), dns_system_resolver_process_query(), dns_system_resolver_resolve(), dump_queue_members(), dup_weakproxy_cb(), fax_detect_attach(), fax_detect_framehook(), fax_detect_framehook_destroy(), fax_detect_new(), fax_gateway_attach(), fax_gateway_detect_t38(), fax_gateway_detect_v21(), fax_gateway_framehook(), fax_gateway_framehook_destroy(), fax_gateway_new(), fax_gateway_request_t38(), fax_gateway_start(), fax_session_new(), fax_session_reserve(), fax_session_tab_complete(), feature_attended_transfer(), find_bridge(), find_channel_control(), find_control(), find_details(), find_hint_by_cb_id(), find_or_create_details(), find_queue_by_name_rt(), find_session(), find_session_by_nonce(), find_user(), format_cap_destroy(), forwards_create_bridge(), forwards_create_channel(), forwards_create_endpoint(), free_members(), function_amiclient(), generic_fax_exec(), get_dsn(), get_languages(), get_member_penalty(), get_member_status(), grab_transfer(), handle_bridge_pairings(), handle_cli_sound_show(), handle_cli_sounds_show(), handle_kickmanconn(), handle_show_hint(), handle_show_hints(), handle_show_named_acl_cmd(), handle_showmanconn(), handle_tcptls_connection(), handle_voicemail_show_aliases(), hangupcause_read(), hepv3_config_post_apply(), hepv3_create_capture_info(), hepv3_data_alloc(), hepv3_send_packet(), history_on_rx_msg(), history_on_tx_msg(), hold(), http_server_discard(), http_server_get(), iax2_codec_pref_string(), iax2_format_compatibility_cap2bitfield(), internal_stasis_subscribe(), jingle_action_hook(), jingle_action_session_initiate(), jingle_add_google_candidates_to_transport(), jingle_add_ice_udp_candidates_to_transport(), jingle_add_payloads_to_description(), jingle_alloc(), jingle_config_alloc(), jingle_endpoint_alloc(), jingle_endpoint_destructor(), jingle_endpoint_state_create(), jingle_endpoint_state_destructor(), jingle_endpoint_state_find_or_create(), jingle_get_rtp_peer(), jingle_hangup(), jingle_interpret_content(), jingle_new(), jingle_read(), jingle_request(), join_conference_bridge(), leave_conference(), load_config(), load_module(), load_users(), local_call(), local_devicestate(), local_hangup(), local_request_with_stream_topology(), locals_show(), manager_add_filter(), manager_queues_status(), manager_queues_summary(), matrix_rebuild(), message_sink_cb(), messaging_app_subscribe_endpoint(), messaging_app_unsubscribe_endpoint(), messaging_cleanup(), messaging_init(), module_config_alloc(), module_config_destructor(), module_config_dtor(), moh_channel_thread(), multicast_rtp_request(), named_acl_config_alloc(), newpvt(), num_available_members(), orig_app(), orig_exten(), parking_config_alloc(), parking_lot_build_or_update(), parking_lot_get_bridge(), parking_lot_get_space(), parking_lot_retrieve_parked_user(), parking_set_duration(), parse_config(), pjsip_acf_channel_read(), pjsip_acf_dial_contacts_read(), pjsip_channel_cli_register(), pjsip_history_entry_alloc(), play_sound(), prepare_bridge_moh_channel(), print_queue(), process_description_file(), publish_cluster_discovery_to_stasis(), publish_cluster_discovery_to_stasis_full(), publish_hint_change(), publish_hint_remove(), purge_sessions(), queue_function_mem_read(), queue_function_qac_dep(), queue_function_queuememberlist(), qupd_exec(), realtime_sqlite3_require(), recording_alloc(), release_obj_or_dsn(), reload_single_member(), reload_single_queue(), remb_enable_collection(), remote_send_hold_refresh(), remove_bridge_playback(), remove_from_playbacks(), remove_from_queue(), ringing(), rna(), rqm_exec(), rt_handle_member_record(), rtp_add_candidates_to_ice(), rtp_raw_write(), session_details_new(), session_do(), set_interval_hook(), sig_pri_call(), sig_pri_cc_monitor_destructor(), sig_pri_unload(), skel_config_alloc(), skel_find_or_create_state(), skel_level_alloc(), sla_calc_station_delays(), sla_choose_idle_trunk(), sla_choose_ringing_trunk(), sla_find_trunk_ref_byname(), sla_queue_event_conf(), sorcery_is_explicit_name_met(), sorcery_object_type_alloc(), sorcery_observer_invocation_alloc(), spandsp_fax_gw_gen_alloc(), stasis_app_bridge_moh_channel(), stasis_app_bridge_moh_stop(), stasis_app_bridge_playback_channel_find(), stasis_app_bridge_playback_channel_remove(), stasis_app_channel_unreal_set_internal(), stasis_app_control_play_uri(), stasis_app_control_record(), stasis_app_control_snoop(), stasis_app_event_allowed(), stasis_app_exec(), stasis_app_get_debug_by_name(), stasis_app_mailboxes_to_json(), stasis_app_recording_options_create(), stasis_app_send(), stasis_app_send_command_async(), stasis_app_subscribe_channel(), stasis_app_to_cli(), stasis_app_unregister(), stasis_app_user_event(), stasis_caching_topic_create(), stasis_caching_unsubscribe(), stasis_caching_unsubscribe_and_join(), stasis_cp_all_create(), stasis_cp_single_create(), stasis_cp_sink_create(), stasis_forward_all(), stasis_init(), stasis_message_create_full(), stasis_message_sink_create(), stasis_message_type_declined(), stasis_state_add_publisher(), stasis_state_add_subscriber(), stasis_state_manager_create(), stasis_state_publish_by_id(), stasis_state_remove_publish_by_id(), stasis_state_subscribe_pool(), stasis_state_topic(), stasis_state_unsubscribe(), stasis_state_unsubscribe_and_join(), stasis_topic_create_with_detail(), stasis_topic_pool_create(), stasis_topic_pool_topic_exists(), stasis_unsubscribe_and_join(), t38_automatic_reject_timer_cb(), t38_change_state(), t38_create_media_state(), t38_framehook(), t38_initialize_session(), t38_parameters_task_data_alloc(), test_core_format_parse_sdp_fmtp(), test_iterator_next(), test_performance(), test_ref(), test_unref(), transport_state_callback(), unhold(), unicast_rtp_request(), unistim_new(), unload_module(), unref_instance_cond(), unref_mansession(), update_connected_line_information(), update_file_format_info(), update_queue(), user_alloc(), websocket_client_parse_uri(), xfer_client_on_evsub_state(), xml_translate(), xmpp_buddy_destructor(), xmpp_client_alloc(), xmpp_client_create_buddy(), xmpp_client_find_or_create(), xmpp_client_service_discovery_result_hook(), xmpp_component_register_get_hook(), xmpp_config_alloc(), xmpp_pak_presence(), xmpp_pak_s10n(), xmpp_pubsub_create_affiliations(), and xmpp_roster_hook().

#define ao2_replace (   dst,
  src 
)    ao2_t_replace((dst), (src), NULL)
#define AO2_STRING_FIELD_CMP_FN (   stype,
  field 
)    AO2_FIELD_CMP_FN(stype, _cmp_fn, field, strcmp, strncmp, AO2_FIELD_TRANSFORM_CMP_FN,)

Creates a compare function for a structure string field.

Parameters
stypeThe structure type
fieldThe string field in the structure to compare

AO2_STRING_FIELD_CMP_FN(mystruct, myfield) will produce a function named mystruct_cmp_fn which compares mystruct->myfield.

AO2_STRING_FIELD_CASE_CMP_FN(mystruct, myfield) would do the same except it performs case insensitive comparisons.

Definition at line 2048 of file astobj2.h.

#define AO2_STRING_FIELD_HASH_FN (   stype,
  field 
)    AO2_FIELD_HASH_FN(stype, field, ast_str_hash)

Creates a hash function for a structure string field.

Parameters
stypeThe structure type
fieldThe string field in the structure to hash

AO2_STRING_FIELD_HASH_FN(mystruct, myfield) will produce a function named mystruct_hash_fn which hashes mystruct->myfield.

AO2_STRING_FIELD_HASH_FN(mystruct, myfield) would do the same except it uses the hash function which ignores case.

Definition at line 2032 of file astobj2.h.

#define AO2_STRING_FIELD_SORT_FN (   stype,
  field 
)    AO2_FIELD_CMP_FN(stype, _sort_fn, field, strcmp, strncmp, AO2_FIELD_TRANSFORM_SORT_FN, const)

Creates a sort function for a structure string field.

Parameters
stypeThe structure type
fieldThe string field in the structure to compare

AO2_STRING_FIELD_SORT_FN(mystruct, myfield) will produce a function named mystruct_sort_fn which compares mystruct->myfield.

AO2_STRING_FIELD_CASE_SORT_FN(mystruct, myfield) would do the same except it performs case insensitive comparisons.

Definition at line 2064 of file astobj2.h.

#define ao2_t_alloc_options (   data_size,
  destructor_fn,
  options,
  debug_msg 
)    __ao2_alloc((data_size), (destructor_fn), (options), (debug_msg), __FILE__, __LINE__, __PRETTY_FUNCTION__)

Allocate and initialize an object.

Parameters
data_sizeThe sizeof() of the user-defined structure.
destructor_fnThe destructor function (can be NULL)
optionsThe ao2 object options (See enum ao2_alloc_opts)
debug_msgAn ao2 object debug tracing message.
Returns
A pointer to user-data.

Allocates a struct astobj2 with sufficient space for the user-defined structure.

Note
  • storage is zeroed; XXX maybe we want a flag to enable/disable this.
  • the refcount of the object just created is 1
  • the returned pointer cannot be free()'d or realloc()'ed; rather, we just call ao2_ref(o, -1);

Definition at line 402 of file astobj2.h.

Referenced by ao2_container_register(), ast_format_create_named(), stasis_message_create_full(), and stasis_message_type_create().

#define ao2_t_callback_data (   container,
  flags,
  cb_fn,
  arg,
  data,
  tag 
)    __ao2_callback_data((container), (flags), (cb_fn), (arg), (data), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)

ao2_callback_data() is a generic function that applies cb_fn() to all objects in a container. It is functionally identical to ao2_callback() except that instead of taking an ao2_callback_fn *, it takes an ao2_callback_data_fn *, and allows the caller to pass in arbitrary data.

This call would be used instead of ao2_callback() when the caller needs to pass OBJ_SEARCH_OBJECT, OBJ_SEARCH_KEY, or OBJ_SEARCH_PARTIAL_KEY as part of the flags argument (which in turn requires passing in a known pointer type for 'arg') and also needs access to other non-global data to complete it's comparison or task.

See the documentation for ao2_callback() for argument descriptions.

See also
ao2_callback()

Definition at line 1721 of file astobj2.h.

#define ao2_t_find (   container,
  arg,
  flags,
  tag 
)    __ao2_find((container), (arg), (flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)

ao2_find() is a short hand for ao2_callback(c, flags, c->cmp_fn, arg) XXX possibly change order of arguments ?

Definition at line 1734 of file astobj2.h.

Referenced by ao2_container_unregister(), find_load_queue_rt_friendly(), find_queue_by_name_rt(), queue_function_queuegetchannel(), queue_function_queuewaitingcount(), reload_queue_members(), reload_single_queue(), and remove_from_queue().

#define ao2_t_weakproxy_ref_object (   weakproxy,
  delta,
  flags,
  tag 
)
Value:
__ao2_weakproxy_ref_object(weakproxy, delta, flags, \
tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 604 of file astobj2.h.

#define ao2_unlink (   container,
  obj 
)    __ao2_unlink((container), (obj), 0, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Remove an object from a container.

Parameters
containerThe container to operate on.
objThe object to unlink.
Return values
NULLalways
Note
The object requested to be unlinked must be valid. However, if it turns out that it is not in the container, this function is still safe to be called.
If the object gets unlinked from the container, the container's reference to the object will be automatically released. (The refcount will be decremented).
Examples:
app_skel.c.

Definition at line 1578 of file astobj2.h.

Referenced by ast_ari_websocket_events_event_websocket_established(), ast_bridge_channel_feature_digit(), ast_bridge_channel_kick(), ast_change_name(), ast_channel_release(), ast_channel_unlink(), ast_endpoint_shutdown(), ast_hangup(), ast_pickup_find_by_group(), ast_sip_sched_task_cancel(), ast_sip_schedule_task(), ast_sorcery_wizard_unregister(), build_calendar(), build_user(), channel_do_masquerade(), conf_ended(), control_unlink(), destroy_gateway(), destroy_v21_sessions(), event_session_cleanup(), fax_session_new(), generic_fax_exec(), handle_channel_snapshot_update_message(), http_server_discard(), jingle_hangup(), join_conference_bridge(), local_hangup(), messaging_app_unsubscribe_endpoint(), moh_channel_thread(), parking_lot_remove_if_unused(), parking_lot_retrieve_parked_user(), reload_single_member(), remove_bridge_playback(), sig_pri_cc_monitor_destructor(), sorcery_proxy_cb(), stasis_app_bridge_destroy(), stasis_app_bridge_playback_channel_remove(), and unpark_parked_user().

#define ao2_unlink_flags (   container,
  obj,
  flags 
)    __ao2_unlink((container), (obj), (flags), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Remove an object from a container.

Parameters
containerThe container to operate on.
objThe object to unlink.
flagssearch_flags to control unlinking the object. (OBJ_NOLOCK)
Return values
NULLalways
Note
The object requested to be unlinked must be valid. However, if it turns out that it is not in the container, this function is still safe to be called.
If the object gets unlinked from the container, the container's reference to the object will be automatically released. (The refcount will be decremented).

Definition at line 1600 of file astobj2.h.

Referenced by ast_format_cache_set(), ast_media_cache_create_or_update(), ast_media_cache_retrieve(), ast_sip_dialog_set_endpoint(), ast_sip_dialog_set_serializer(), ast_sorcery_object_unregister(), ast_taskprocessor_unreference(), remove_from_playbacks(), and xmpp_pak_presence().

#define AO2_WEAKPROXY ( )    struct ao2_weakproxy __weakproxy##__LINE__

Macro which must be used at the beginning of weakproxy capable objects.

Note
The primary purpose of user defined fields on weakproxy objects is to hold immutable container keys for the real object.

Definition at line 538 of file astobj2.h.

#define ao2_weakproxy_alloc (   data_size,
  destructor_fn 
)    __ao2_weakproxy_alloc(data_size, destructor_fn, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Allocate an ao2_weakproxy object.

Since
14.0.0
Parameters
data_sizeThe sizeof() of the user-defined structure.
destructor_fnThe destructor function (can be NULL)
Note
"struct ao2_weakproxy" must be the first field of any object. This can be done by using AO2_WEAKPROXY to declare your structure.

Definition at line 550 of file astobj2.h.

#define ao2_weakproxy_find (   c,
  arg,
  flags,
  tag 
)    __ao2_weakproxy_find(c, arg, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Perform an ao2_find on a container with ao2_weakproxy objects, returning the real object.

Note
Only OBJ_SEARCH_* and OBJ_NOLOCK flags are supported by this function.
See also
ao2_callback for description of arguments.

Definition at line 1748 of file astobj2.h.

Referenced by ast_sorcery_retrieve_by_module_name(), stasis_state_remove_publish_by_id(), and stasis_topic_get().

#define ao2_weakproxy_get_object (   weakproxy,
  flags 
)    __ao2_weakproxy_get_object(weakproxy, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Get the object associated with weakproxy.

Since
14.0.0
Parameters
weakproxyThe weakproxy to read from.
flagsOBJ_NOLOCK to avoid locking weakproxy.
Returns
A reference to the object previously set by ao2_weakproxy_set_object.
Return values
NULLEither no object was set or the previously set object has been freed.

Definition at line 621 of file astobj2.h.

Referenced by dup_weakproxy_cb().

#define ao2_weakproxy_ref_object (   weakproxy,
  delta,
  flags 
)    ao2_t_weakproxy_ref_object(weakproxy, delta, flags, NULL)

Run ao2_t_ref on the object associated with weakproxy.

Since
14.0.0
Parameters
weakproxyThe weakproxy to read from.
deltaValue to add to the reference counter.
flagsOBJ_NOLOCK to avoid locking weakproxy.
Return values
-2weakproxy is not a valid ao2_weakproxy.
-1weakproxy has no associated object.
Returns
The value of the reference counter before the operation.

Definition at line 601 of file astobj2.h.

#define ao2_weakproxy_set_object (   weakproxy,
  obj,
  flags 
)    __ao2_weakproxy_set_object(weakproxy, obj, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Associate weakproxy with obj.

Since
14.0.0
Parameters
weakproxyAn object created by ao2_weakproxy_alloc.
objAn ao2 object not created by ao2_weakproxy_alloc.
flagsOBJ_NOLOCK to avoid locking weakproxy.
Return values
0Success
-1Failure
Note
obj must be newly created, this procedure is not thread safe if any other code can reach obj before this procedure ends.
weakproxy may be previously existing, but must not currently have an object set.
The only way to unset an object is for it to be destroyed. Any call to this function while an object is already set will fail.

Definition at line 579 of file astobj2.h.

#define OBJ_KEY   OBJ_SEARCH_KEY

Deprecated name

Examples:
app_skel.c.

Definition at line 1151 of file astobj2.h.

Referenced by __ast_bucket_scheme_register(), __ast_sorcery_apply_default(), __ast_sorcery_object_field_register(), __ast_sorcery_object_register(), __ast_sorcery_object_type_insert_wizard(), __ast_sorcery_remove_wizard_mapping(), __ast_sorcery_wizard_register(), agent_login_exec(), agent_request_exec(), alloc_variant(), ast_bucket_alloc(), ast_bucket_file_alloc(), ast_bucket_file_metadata_get(), ast_bucket_file_metadata_set(), ast_bucket_file_metadata_unset(), ast_channel_dialed_causes_add(), ast_channel_dialed_causes_find(), ast_channel_get_by_name_prefix(), ast_channel_iterator_by_name_new(), ast_endpoint_find_by_id(), ast_media_get_variants(), ast_sorcery_alloc(), ast_sorcery_copy(), ast_sorcery_create(), ast_sorcery_delete(), ast_sorcery_diff(), ast_sorcery_force_reload_object(), ast_sorcery_get_wizard_mapping(), ast_sorcery_get_wizard_mapping_count(), ast_sorcery_is_stale(), ast_sorcery_load_object(), ast_sorcery_object_fields_register(), ast_sorcery_object_set_copy_handler(), ast_sorcery_object_set_diff_handler(), ast_sorcery_objectset_apply(), ast_sorcery_objectset_create2(), ast_sorcery_objectset_json_create(), ast_sorcery_observer_add(), ast_sorcery_observer_remove(), ast_sorcery_reload_object(), ast_sorcery_retrieve_by_fields(), ast_sorcery_retrieve_by_prefix(), ast_sorcery_retrieve_by_regex(), ast_sorcery_update(), ast_taskprocessor_create_with_listener(), ast_taskprocessor_get(), authenticate_request(), bridge_cmp_cb(), bucket_file_wizard_retrieve(), bucket_rbtree_str_sort_cmp(), bucket_wizard_retrieve(), build_peer(), build_user(), conf_find_bridge(), conf_find_bridge_profile(), conf_find_user_profile(), conf_set_menu_to_user(), conference_bridge_cmp_cb(), conference_bridge_hash_cb(), find_member_by_queuename_and_interface(), find_peer(), http_server_get_by_addr(), iax2_destroy_helper(), jingle_action_hook(), jingle_endpoint_cmp(), jingle_endpoint_find(), jingle_endpoint_hash(), jingle_request(), jingle_session_cmp(), jingle_session_hash(), join_conference_bridge(), menu_cmp_cb(), named_item_find(), peer_cmp_cb(), peer_hash_cb(), protocol_cmp_fn(), protocol_hash_fn(), skel_find_or_create_state(), skel_level_find(), sorcery_memory_cmp(), sorcery_memory_hash(), sorcery_reloadable(), stasis_app_control_record(), stasis_app_playback_find_by_id(), stasis_app_recording_find_by_name(), tps_cmp_cb(), tps_hash_cb(), user_cmp_cb(), user_hash_cb(), xmpp_buddy_cmp(), xmpp_buddy_hash(), xmpp_client_service_discovery_result_hook(), xmpp_component_register_get_hook(), xmpp_config_cmp(), xmpp_config_find(), xmpp_pak_message(), xmpp_pak_presence(), xmpp_pak_s10n(), xmpp_resource_hash(), and xmpp_roster_hook().

#define OBJ_PARTIAL_KEY   OBJ_SEARCH_PARTIAL_KEY
#define OBJ_POINTER   OBJ_SEARCH_OBJECT

Typedef Documentation

typedef int( ao2_callback_data_fn) (void *obj, void *arg, void *data, int flags)

Type of a generic callback function.

Parameters
objpointer to the (user-defined part) of an object.
argcallback argument from ao2_callback()
dataarbitrary data from ao2_callback()
flagsflags from ao2_callback() OBJ_SEARCH_OBJECT - if set, 'arg', is an object. OBJ_SEARCH_KEY - if set, 'arg', is a search key item that is not an object. OBJ_SEARCH_PARTIAL_KEY - if set, 'arg', is a partial search key item that is not an object.

The return values are a combination of enum _cb_results. Callback functions are used to search or manipulate objects in a container.

Definition at line 1244 of file astobj2.h.

typedef int( ao2_callback_fn) (void *obj, void *arg, int flags)

Type of a generic callback function.

Parameters
objpointer to the (user-defined part) of an object.
argcallback argument from ao2_callback()
flagsflags from ao2_callback() OBJ_SEARCH_OBJECT - if set, 'arg', is an object. OBJ_SEARCH_KEY - if set, 'arg', is a search key item that is not an object. OBJ_SEARCH_PARTIAL_KEY - if set, 'arg', is a partial search key item that is not an object.

The return values are a combination of enum _cb_results. Callback functions are used to search or manipulate objects in a container.

Definition at line 1226 of file astobj2.h.

typedef void(* ao2_destructor_fn) (void *vdoomed)

Typedef for an object destructor.

Parameters
vdoomedObject to destroy.

This is called just before freeing the memory for the object. It is passed a pointer to the user-defined data of the object.

Definition at line 358 of file astobj2.h.

typedef int( ao2_hash_fn) (const void *obj, int flags)

Type of a generic function to generate a hash value from an object.

Parameters
objpointer to the (user-defined part) of an object.
flagsflags from ao2_callback() OBJ_SEARCH_OBJECT - if set, 'obj', is an object. OBJ_SEARCH_KEY - if set, 'obj', is a search key item that is not an object.
Note
This function must be idempotent.
Returns
Computed hash value.

Definition at line 1258 of file astobj2.h.

typedef void( ao2_prnt_fn) (void *where, const char *fmt,...)

Print output.

Since
12.0.0
Parameters
whereUser data pointer needed to determine where to put output.
fmtprintf type format string.

Definition at line 1435 of file astobj2.h.

typedef void( ao2_prnt_obj_fn) (void *v_obj, void *where, ao2_prnt_fn *prnt)

Print object key.

Since
12.0.0
Parameters
v_objA pointer to the object we want the key printed.
whereUser data needed by prnt to determine where to put output.
prntPrint output callback function to use.

Definition at line 1445 of file astobj2.h.

typedef int( ao2_sort_fn) (const void *obj_left, const void *obj_right, int flags)

Type of generic container sort function.

Parameters
obj_leftpointer to the (user-defined part) of an object.
obj_rightpointer to the (user-defined part) of an object.
flagsflags from ao2_callback() OBJ_SEARCH_OBJECT - if set, 'obj_right', is an object. OBJ_SEARCH_KEY - if set, 'obj_right', is a search key item that is not an object. OBJ_SEARCH_PARTIAL_KEY - if set, 'obj_right', is a partial search key item that is not an object.
Note
This function must be idempotent.
Return values
negtaiveif obj_left < obj_right
0if obj_left == obj_right
positiveif obj_left > obj_right

Definition at line 1276 of file astobj2.h.

Enumeration Type Documentation

A callback function will return a combination of CMP_MATCH and CMP_STOP. The latter will terminate the search in a container.

Enumerator
CMP_MATCH 

the object matches the request

CMP_STOP 

stop the search now

Definition at line 1026 of file astobj2.h.

1026  {
1027  CMP_MATCH = 0x1, /*!< the object matches the request */
1028  CMP_STOP = 0x2, /*!< stop the search now */
1029 };

Options available when allocating an ao2 object.

Enumerator
AO2_ALLOC_OPT_LOCK_MUTEX 

The ao2 object has a recursive mutex lock associated with it.

AO2_ALLOC_OPT_LOCK_RWLOCK 

The ao2 object has a non-recursive read/write lock associated with it.

AO2_ALLOC_OPT_LOCK_NOLOCK 

The ao2 object has no lock associated with it.

AO2_ALLOC_OPT_LOCK_MASK 

The ao2 object locking option field mask.

AO2_ALLOC_OPT_NO_REF_DEBUG 

The ao2 object will not record any REF_DEBUG entries

Definition at line 361 of file astobj2.h.

361  {
362  /*! The ao2 object has a recursive mutex lock associated with it. */
363  AO2_ALLOC_OPT_LOCK_MUTEX = (0 << 0),
364  /*! The ao2 object has a non-recursive read/write lock associated with it. */
365  AO2_ALLOC_OPT_LOCK_RWLOCK = (1 << 0),
366  /*! The ao2 object has no lock associated with it. */
367  AO2_ALLOC_OPT_LOCK_NOLOCK = (2 << 0),
368  /*! The ao2 object locking option field mask. */
369  AO2_ALLOC_OPT_LOCK_MASK = (3 << 0),
370  /*!
371  * \internal The ao2 object uses a separate object for locking.
372  *
373  * \note This option is used internally by ao2_alloc_with_lockobj and
374  * should never be passed directly to ao2_alloc.
375  */
376  AO2_ALLOC_OPT_LOCK_OBJ = AO2_ALLOC_OPT_LOCK_MASK,
377  /*! The ao2 object will not record any REF_DEBUG entries */
378  AO2_ALLOC_OPT_NO_REF_DEBUG = (1 << 2),
379 };

Options available when allocating an ao2 container object.

Note
Each option is open to some interpretation by the container type as long as it makes sense with the option name.
Enumerator
AO2_CONTAINER_ALLOC_OPT_INSERT_BEGIN 

Insert objects at the beginning of the container. (Otherwise it is the opposite; insert at the end.)

Note
If an ao2_sort_fn is provided, the object is inserted before any objects with duplicate keys.
Hash containers insert the object in the computed hash bucket in the indicated manner.
AO2_CONTAINER_ALLOC_OPT_DUPS_MASK 

The ao2 container objects with duplicate keys option field mask.

AO2_CONTAINER_ALLOC_OPT_DUPS_ALLOW 

Allow objects with duplicate keys in container.

AO2_CONTAINER_ALLOC_OPT_DUPS_REJECT 

Reject objects with duplicate keys in container.

Note
The container must be sorted. i.e. have an ao2_sort_fn.
AO2_CONTAINER_ALLOC_OPT_DUPS_OBJ_REJECT 

Reject duplicate objects in container.

Don't link the same object into the container twice. However, you can link a different object with the same key.

Note
The container must be sorted. i.e. have an ao2_sort_fn.
It is assumed that the objects are located where the search key says they should be located.
AO2_CONTAINER_ALLOC_OPT_DUPS_REPLACE 

Replace objects with duplicate keys in container.

The existing duplicate object is removed and the new object takes the old object's place.

Note
The container must be sorted. i.e. have an ao2_sort_fn.

Definition at line 1161 of file astobj2.h.

1161  {
1162  /*!
1163  * \brief Insert objects at the beginning of the container.
1164  * (Otherwise it is the opposite; insert at the end.)
1165  *
1166  * \note If an ao2_sort_fn is provided, the object is inserted
1167  * before any objects with duplicate keys.
1168  *
1169  * \note Hash containers insert the object in the computed hash
1170  * bucket in the indicated manner.
1171  */
1173 
1174  /*!
1175  * \brief The ao2 container objects with duplicate keys option field mask.
1176  */
1178  /*!
1179  * \brief Allow objects with duplicate keys in container.
1180  */
1182  /*!
1183  * \brief Reject objects with duplicate keys in container.
1184  *
1185  * \note The container must be sorted. i.e. have an
1186  * ao2_sort_fn.
1187  */
1189  /*!
1190  * \brief Reject duplicate objects in container.
1191  *
1192  * \details Don't link the same object into the container twice.
1193  * However, you can link a different object with the same key.
1194  *
1195  * \note The container must be sorted. i.e. have an
1196  * ao2_sort_fn.
1197  *
1198  * \note It is assumed that the objects are located where the
1199  * search key says they should be located.
1200  */
1202  /*!
1203  * \brief Replace objects with duplicate keys in container.
1204  *
1205  * \details The existing duplicate object is removed and the new
1206  * object takes the old object's place.
1207  *
1208  * \note The container must be sorted. i.e. have an
1209  * ao2_sort_fn.
1210  */
1212 };
Allow objects with duplicate keys in container.
Definition: astobj2.h:1181
Insert objects at the beginning of the container. (Otherwise it is the opposite; insert at the end...
Definition: astobj2.h:1172
The ao2 container objects with duplicate keys option field mask.
Definition: astobj2.h:1177
Replace objects with duplicate keys in container.
Definition: astobj2.h:1211
Reject objects with duplicate keys in container.
Definition: astobj2.h:1188
Reject duplicate objects in container.
Definition: astobj2.h:1201

Flags that can be passed to ao2_iterator_init() to modify the behavior of the iterator.

Enumerator
AO2_ITERATOR_DONTLOCK 

Assume that the ao2_container is already locked.

Note
For ao2_containers that have mutexes, no locking will be done.
For ao2_containers that have RWLOCKs, the lock will be promoted to write mode as needed. The lock will be returned to the original locked state.
Only use this flag if the ao2_container is manually locked already. You should hold the lock until after ao2_iterator_destroy(). If you must release the lock then you must at least hold the lock whenever you call an ao2_iterator_xxx function with this iterator.
AO2_ITERATOR_MALLOCD 

Indicates that the iterator was dynamically allocated by astobj2 API and should be freed by ao2_iterator_destroy().

AO2_ITERATOR_UNLINK 

Indicates that before the iterator returns an object from the container being iterated, the object should be unlinked from the container.

AO2_ITERATOR_DESCENDING 

Iterate in descending order (Last to first container object) (Otherwise ascending order)

Note
Other traversal orders such as pre-order and post-order do not make sense because they require the container structure to be static during the traversal. Iterators just about guarantee that is not going to happen because the container is allowed to change by other threads during the iteration.

Definition at line 1835 of file astobj2.h.

1835  {
1836  /*!
1837  * \brief Assume that the ao2_container is already locked.
1838  *
1839  * \note For ao2_containers that have mutexes, no locking will
1840  * be done.
1841  *
1842  * \note For ao2_containers that have RWLOCKs, the lock will be
1843  * promoted to write mode as needed. The lock will be returned
1844  * to the original locked state.
1845  *
1846  * \note Only use this flag if the ao2_container is manually
1847  * locked already. You should hold the lock until after
1848  * ao2_iterator_destroy(). If you must release the lock then
1849  * you must at least hold the lock whenever you call an
1850  * ao2_iterator_xxx function with this iterator.
1851  */
1852  AO2_ITERATOR_DONTLOCK = (1 << 0),
1853  /*!
1854  * Indicates that the iterator was dynamically allocated by
1855  * astobj2 API and should be freed by ao2_iterator_destroy().
1856  */
1857  AO2_ITERATOR_MALLOCD = (1 << 1),
1858  /*!
1859  * Indicates that before the iterator returns an object from
1860  * the container being iterated, the object should be unlinked
1861  * from the container.
1862  */
1863  AO2_ITERATOR_UNLINK = (1 << 2),
1864  /*!
1865  * Iterate in descending order (Last to first container object)
1866  * (Otherwise ascending order)
1867  *
1868  * \note Other traversal orders such as pre-order and post-order
1869  * do not make sense because they require the container
1870  * structure to be static during the traversal. Iterators just
1871  * about guarantee that is not going to happen because the
1872  * container is allowed to change by other threads during the
1873  * iteration.
1874  */
1875  AO2_ITERATOR_DESCENDING = (1 << 3),
1876 };
Assume that the ao2_container is already locked.
Definition: astobj2.h:1852

Which lock to request.

Enumerator
AO2_LOCK_REQ_MUTEX 

Request the mutex lock be acquired.

AO2_LOCK_REQ_RDLOCK 

Request the read lock be acquired.

AO2_LOCK_REQ_WRLOCK 

Request the write lock be acquired.

Definition at line 700 of file astobj2.h.

700  {
701  /*! Request the mutex lock be acquired. */
703  /*! Request the read lock be acquired. */
705  /*! Request the write lock be acquired. */
707 };

Flags passed to ao2_callback_fn(), ao2_hash_fn(), and ao2_sort_fn() to modify behaviour.

Enumerator
OBJ_UNLINK 

Unlink the object for which the callback function returned CMP_MATCH.

OBJ_NODATA 

On match, don't return the object hence do not increase its refcount.

OBJ_MULTIPLE 

Don't stop at the first match in ao2_callback() unless the result of the callback function has the CMP_STOP bit set.

OBJ_NOLOCK 

Assume that the ao2_container is already locked.

Note
For ao2_containers that have mutexes, no locking will be done.
For ao2_containers that have RWLOCKs, the lock will be promoted to write mode as needed. The lock will be returned to the original locked state.
Only use this flag if the ao2_container is manually locked already.
OBJ_SEARCH_MASK 

Search option field mask.

Todo:
Eventually OBJ_SEARCH_MASK will shrink to a two bit field when the codebase is made to use the search field values as a field instead of independent bits.
OBJ_SEARCH_NONE 

The arg parameter has no meaning to the astobj2 code.

OBJ_SEARCH_OBJECT 

The arg parameter is an object of the same type.

The arg parameter is an object of the same type as the one being searched for, so use the object's ao2_hash_fn and/or ao2_sort_fn functions for optimized searching.

Note
The supplied ao2_callback_fn is called after the container nodes have been filtered by the ao2_hash_fn and/or ao2_sort_fn functions.
OBJ_SEARCH_KEY 

The arg parameter is a search key, but is not an object.

This can be used when you want to be able to pass custom data to the container's stored ao2_hash_fn, ao2_sort_fn, and ao2_find ao2_callback_fn functions that is not a full object, but perhaps just a string.

Note
The supplied ao2_callback_fn is called after the container nodes have been filtered by the ao2_hash_fn and/or ao2_sort_fn functions.
OBJ_SEARCH_PARTIAL_KEY 

The arg parameter is a partial search key similar to OBJ_SEARCH_KEY.

The partial key can be used by the ao2_sort_fn to guide the search to find a contiguous subset of a sorted container. For example, a sorted container holds: "A", "B", "Bert", "Beth", "Earnie". Doing a partial key search with "B" will find the sorted subset of all held objects starting with "B".

Note
The supplied ao2_callback_fn is called after the container nodes have been filtered by the ao2_sort_fn function.
OBJ_ORDER_MASK 

Traverse order option field mask.

OBJ_ORDER_ASCENDING 

Traverse in ascending order (First to last container object)

OBJ_ORDER_DESCENDING 

Traverse in descending order (Last to first container object)

OBJ_ORDER_PRE 

Traverse in pre-order (Node then children, for tree container)

Note
For non-tree containers, it is up to the container type to make the best interpretation of the order. For list and hash containers, this also means ascending order because a binary tree can degenerate into a list.
OBJ_ORDER_POST 

Traverse in post-order (Children then node, for tree container)

Note
For non-tree containers, it is up to the container type to make the best interpretation of the order. For list and hash containers, this also means descending order because a binary tree can degenerate into a list.

Definition at line 1034 of file astobj2.h.

1034  {
1035  /*!
1036  * Unlink the object for which the callback function returned
1037  * CMP_MATCH.
1038  */
1039  OBJ_UNLINK = (1 << 0),
1040  /*!
1041  * On match, don't return the object hence do not increase its
1042  * refcount.
1043  */
1044  OBJ_NODATA = (1 << 1),
1045  /*!
1046  * Don't stop at the first match in ao2_callback() unless the
1047  * result of the callback function has the CMP_STOP bit set.
1048  */
1049  OBJ_MULTIPLE = (1 << 2),
1050  /*!
1051  * \brief Assume that the ao2_container is already locked.
1052  *
1053  * \note For ao2_containers that have mutexes, no locking will
1054  * be done.
1055  *
1056  * \note For ao2_containers that have RWLOCKs, the lock will be
1057  * promoted to write mode as needed. The lock will be returned
1058  * to the original locked state.
1059  *
1060  * \note Only use this flag if the ao2_container is manually
1061  * locked already.
1062  */
1063  OBJ_NOLOCK = (1 << 4),
1064 
1065  /*!
1066  * \brief Search option field mask.
1067  *
1068  * \todo Eventually OBJ_SEARCH_MASK will shrink to a two bit
1069  * field when the codebase is made to use the search field
1070  * values as a field instead of independent bits.
1071  */
1072  OBJ_SEARCH_MASK = (0x07 << 5),
1073  /*! \brief The arg parameter has no meaning to the astobj2 code. */
1074  OBJ_SEARCH_NONE = (0 << 5),
1075  /*!
1076  * \brief The arg parameter is an object of the same type.
1077  *
1078  * \details
1079  * The arg parameter is an object of the same type as the one
1080  * being searched for, so use the object's ao2_hash_fn and/or
1081  * ao2_sort_fn functions for optimized searching.
1082  *
1083  * \note The supplied ao2_callback_fn is called after the
1084  * container nodes have been filtered by the ao2_hash_fn and/or
1085  * ao2_sort_fn functions.
1086  */
1087  OBJ_SEARCH_OBJECT = (1 << 5),
1088  /*!
1089  * \brief The arg parameter is a search key, but is not an object.
1090  *
1091  * \details
1092  * This can be used when you want to be able to pass custom data
1093  * to the container's stored ao2_hash_fn, ao2_sort_fn, and
1094  * ao2_find ao2_callback_fn functions that is not a full object,
1095  * but perhaps just a string.
1096  *
1097  * \note The supplied ao2_callback_fn is called after the
1098  * container nodes have been filtered by the ao2_hash_fn and/or
1099  * ao2_sort_fn functions.
1100  */
1101  OBJ_SEARCH_KEY = (2 << 5),
1102  /*!
1103  * \brief The arg parameter is a partial search key similar to OBJ_SEARCH_KEY.
1104  *
1105  * \details
1106  * The partial key can be used by the ao2_sort_fn to guide the
1107  * search to find a contiguous subset of a sorted container.
1108  * For example, a sorted container holds: "A", "B", "Bert",
1109  * "Beth", "Earnie". Doing a partial key search with "B" will
1110  * find the sorted subset of all held objects starting with "B".
1111  *
1112  * \note The supplied ao2_callback_fn is called after the
1113  * container nodes have been filtered by the ao2_sort_fn
1114  * function.
1115  */
1116  OBJ_SEARCH_PARTIAL_KEY = (4 << 5),
1117 
1118  /*! \brief Traverse order option field mask. */
1119  OBJ_ORDER_MASK = (0x03 << 8),
1120  /*! \brief Traverse in ascending order (First to last container object) */
1121  OBJ_ORDER_ASCENDING = (0 << 8),
1122  /*! \brief Traverse in descending order (Last to first container object) */
1123  OBJ_ORDER_DESCENDING = (1 << 8),
1124  /*!
1125  * \brief Traverse in pre-order (Node then children, for tree container)
1126  *
1127  * \note For non-tree containers, it is up to the container type
1128  * to make the best interpretation of the order. For list and
1129  * hash containers, this also means ascending order because a
1130  * binary tree can degenerate into a list.
1131  */
1132  OBJ_ORDER_PRE = (2 << 8),
1133  /*!
1134  * \brief Traverse in post-order (Children then node, for tree container)
1135  *
1136  * \note For non-tree containers, it is up to the container type
1137  * to make the best interpretation of the order. For list and
1138  * hash containers, this also means descending order because a
1139  * binary tree can degenerate into a list.
1140  */
1141  OBJ_ORDER_POST = (3 << 8),
1142 };
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
Assume that the ao2_container is already locked.
Definition: astobj2.h:1063
The arg parameter has no meaning to the astobj2 code.
Definition: astobj2.h:1074
Traverse in ascending order (First to last container object)
Definition: astobj2.h:1121
The arg parameter is a partial search key similar to OBJ_SEARCH_KEY.
Definition: astobj2.h:1116
Traverse in descending order (Last to first container object)
Definition: astobj2.h:1123
Traverse in pre-order (Node then children, for tree container)
Definition: astobj2.h:1132
The arg parameter is an object of the same type.
Definition: astobj2.h:1087
Traverse in post-order (Children then node, for tree container)
Definition: astobj2.h:1141
Search option field mask.
Definition: astobj2.h:1072
Traverse order option field mask.
Definition: astobj2.h:1119

Function Documentation

void __ao2_cleanup ( void *  obj)

gcc attribute(cleanup()) functions

Note
they must be able to handle NULL parameters because most of the allocation/find functions can fail and we don't want to try to tear down a NULL

Definition at line 677 of file astobj2.c.

References ao2_ref.

Referenced by agent_request_exec(), ast_ari_bridges_set_video_source(), bridge_agent_hold_push(), dial_bridge_after_cb(), and parking_set_duration().

678 {
679  if (obj) {
680  ao2_ref(obj, -1);
681  }
682 }
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
void * obj
Definition: astobj2.h:807
void* __ao2_find ( struct ao2_container c,
const void *  arg,
enum search_flags  flags,
const char *  tag,
const char *  file,
int  line,
const char *  func 
)

the find function just invokes the default callback with some reasonable flags.

Definition at line 427 of file astobj2_container.c.

References ao2_container::cmp_fn.

429 {
430  void *arged = (void *) arg;/* Done to avoid compiler const warning */
431 
432  if (!c) {
433  /* Sanity checks. */
434  ast_assert(0);
435  return NULL;
436  }
437  return __ao2_callback(c, flags, c->cmp_fn, arged, tag, file, line, func);
438 }
ao2_callback_fn * cmp_fn
int __ao2_lock ( void *  a,
enum ao2_lock_req  lock_how,
const char *  file,
const char *  func,
int  line,
const char *  var 
)

Lock an object.

Parameters
aA pointer to the object we want to lock.
lock_how,file,func,line,var
Returns
0 on success, other values on error.

Definition at line 222 of file astobj2.c.

References __INTERNAL_OBJ_CHECK, AO2_ALLOC_OPT_LOCK_MASK, AO2_ALLOC_OPT_LOCK_MUTEX, AO2_ALLOC_OPT_LOCK_NOLOCK, AO2_ALLOC_OPT_LOCK_RWLOCK, AO2_LOCK_REQ_MUTEX, AO2_LOCK_REQ_RDLOCK, AO2_LOCK_REQ_WRLOCK, ast_atomic_fetchadd_int(), __priv_data::lockused, ao2_rwlock_priv::num_lockers, and __priv_data::options.

223 {
224  struct astobj2 *obj = __INTERNAL_OBJ_CHECK(user_data, file, line, func);
225  struct astobj2_lock *obj_mutex;
226  struct astobj2_rwlock *obj_rwlock;
227  struct astobj2_lockobj *obj_lockobj;
228  int res = 0;
229 
230  if (obj == NULL) {
231  return -1;
232  }
233 
234  if (ref_log) {
235  obj->priv_data.lockused = 1;
236  }
237 
238  switch (obj->priv_data.options & AO2_ALLOC_OPT_LOCK_MASK) {
240  obj_mutex = INTERNAL_OBJ_MUTEX(user_data);
241  res = __ast_pthread_mutex_lock(file, line, func, var, &obj_mutex->mutex.lock);
242 #ifdef AO2_DEBUG
243  if (!res) {
244  ast_atomic_fetchadd_int(&ao2.total_locked, 1);
245  }
246 #endif
247  break;
249  obj_rwlock = INTERNAL_OBJ_RWLOCK(user_data);
250  switch (lock_how) {
251  case AO2_LOCK_REQ_MUTEX:
252  case AO2_LOCK_REQ_WRLOCK:
253  res = __ast_rwlock_wrlock(file, line, func, &obj_rwlock->rwlock.lock, var);
254  if (!res) {
255  ast_atomic_fetchadd_int(&obj_rwlock->rwlock.num_lockers, -1);
256 #ifdef AO2_DEBUG
257  ast_atomic_fetchadd_int(&ao2.total_locked, 1);
258 #endif
259  }
260  break;
261  case AO2_LOCK_REQ_RDLOCK:
262  res = __ast_rwlock_rdlock(file, line, func, &obj_rwlock->rwlock.lock, var);
263  if (!res) {
264  ast_atomic_fetchadd_int(&obj_rwlock->rwlock.num_lockers, +1);
265 #ifdef AO2_DEBUG
266  ast_atomic_fetchadd_int(&ao2.total_locked, 1);
267 #endif
268  }
269  break;
270  }
271  break;
273  /* The ao2 object has no lock. */
274  break;
275  case AO2_ALLOC_OPT_LOCK_OBJ:
276  obj_lockobj = INTERNAL_OBJ_LOCKOBJ(user_data);
277  res = __ao2_lock(obj_lockobj->lockobj.lock, lock_how, file, func, line, var);
278  break;
279  default:
280  ast_log(__LOG_ERROR, file, line, func, "Invalid lock option on ao2 object %p\n",
281  user_data);
282  return -1;
283  }
284 
285  return res;
286 }
uint32_t options
The ao2 object option flags.
Definition: astobj2.c:70
int __ao2_lock(void *user_data, enum ao2_lock_req lock_how, const char *file, const char *func, int line, const char *var)
Lock an object.
Definition: astobj2.c:222
#define __INTERNAL_OBJ_CHECK(user_data, file, line, func)
convert from a pointer _p to a user-defined object
Definition: astobj2.c:171
int ast_atomic_fetchadd_int(volatile int *p, int v)
Atomically add v to *p and return the previous value of *p.
Definition: lock.h:757
uint32_t lockused
Set to 1 when the lock is used if refdebug is enabled.
Definition: astobj2.c:77
int __ao2_trylock ( void *  a,
enum ao2_lock_req  lock_how,
const char *  file,
const char *  func,
int  line,
const char *  var 
)

Try locking– (don't block if fail)

Parameters
aA pointer to the object we want to lock.
lock_how,file,func,line,var
Returns
0 on success, other values on error.

Definition at line 342 of file astobj2.c.

References __INTERNAL_OBJ_CHECK, AO2_ALLOC_OPT_LOCK_MASK, AO2_ALLOC_OPT_LOCK_MUTEX, AO2_ALLOC_OPT_LOCK_NOLOCK, AO2_ALLOC_OPT_LOCK_RWLOCK, AO2_LOCK_REQ_MUTEX, AO2_LOCK_REQ_RDLOCK, AO2_LOCK_REQ_WRLOCK, ast_atomic_fetchadd_int(), __priv_data::lockused, ao2_rwlock_priv::num_lockers, and __priv_data::options.

343 {
344  struct astobj2 *obj = __INTERNAL_OBJ_CHECK(user_data, file, line, func);
345  struct astobj2_lock *obj_mutex;
346  struct astobj2_rwlock *obj_rwlock;
347  struct astobj2_lockobj *obj_lockobj;
348  int res = 0;
349 
350  if (obj == NULL) {
351  return -1;
352  }
353 
354  if (ref_log) {
355  obj->priv_data.lockused = 1;
356  }
357 
358  switch (obj->priv_data.options & AO2_ALLOC_OPT_LOCK_MASK) {
360  obj_mutex = INTERNAL_OBJ_MUTEX(user_data);
361  res = __ast_pthread_mutex_trylock(file, line, func, var, &obj_mutex->mutex.lock);
362 #ifdef AO2_DEBUG
363  if (!res) {
364  ast_atomic_fetchadd_int(&ao2.total_locked, 1);
365  }
366 #endif
367  break;
369  obj_rwlock = INTERNAL_OBJ_RWLOCK(user_data);
370  switch (lock_how) {
371  case AO2_LOCK_REQ_MUTEX:
372  case AO2_LOCK_REQ_WRLOCK:
373  res = __ast_rwlock_trywrlock(file, line, func, &obj_rwlock->rwlock.lock, var);
374  if (!res) {
375  ast_atomic_fetchadd_int(&obj_rwlock->rwlock.num_lockers, -1);
376 #ifdef AO2_DEBUG
377  ast_atomic_fetchadd_int(&ao2.total_locked, 1);
378 #endif
379  }
380  break;
381  case AO2_LOCK_REQ_RDLOCK:
382  res = __ast_rwlock_tryrdlock(file, line, func, &obj_rwlock->rwlock.lock, var);
383  if (!res) {
384  ast_atomic_fetchadd_int(&obj_rwlock->rwlock.num_lockers, +1);
385 #ifdef AO2_DEBUG
386  ast_atomic_fetchadd_int(&ao2.total_locked, 1);
387 #endif
388  }
389  break;
390  }
391  break;
393  /* The ao2 object has no lock. */
394  return 0;
395  case AO2_ALLOC_OPT_LOCK_OBJ:
396  obj_lockobj = INTERNAL_OBJ_LOCKOBJ(user_data);
397  res = __ao2_trylock(obj_lockobj->lockobj.lock, lock_how, file, func, line, var);
398  break;
399  default:
400  ast_log(__LOG_ERROR, file, line, func, "Invalid lock option on ao2 object %p\n",
401  user_data);
402  return -1;
403  }
404 
405  return res;
406 }
int __ao2_trylock(void *user_data, enum ao2_lock_req lock_how, const char *file, const char *func, int line, const char *var)
Try locking– (don't block if fail)
Definition: astobj2.c:342
uint32_t options
The ao2 object option flags.
Definition: astobj2.c:70
#define __INTERNAL_OBJ_CHECK(user_data, file, line, func)
convert from a pointer _p to a user-defined object
Definition: astobj2.c:171
int ast_atomic_fetchadd_int(volatile int *p, int v)
Atomically add v to *p and return the previous value of *p.
Definition: lock.h:757
uint32_t lockused
Set to 1 when the lock is used if refdebug is enabled.
Definition: astobj2.c:77
int __ao2_unlock ( void *  a,
const char *  file,
const char *  func,
int  line,
const char *  var 
)

Unlock an object.

Parameters
aA pointer to the object we want unlock.
file,func,line,var
Returns
0 on success, other values on error.

Definition at line 288 of file astobj2.c.

References __INTERNAL_OBJ_CHECK, AO2_ALLOC_OPT_LOCK_MASK, AO2_ALLOC_OPT_LOCK_MUTEX, AO2_ALLOC_OPT_LOCK_NOLOCK, AO2_ALLOC_OPT_LOCK_RWLOCK, ast_atomic_fetchadd_int(), ao2_rwlock_priv::num_lockers, and __priv_data::options.

289 {
290  struct astobj2 *obj = __INTERNAL_OBJ_CHECK(user_data, file, line, func);
291  struct astobj2_lock *obj_mutex;
292  struct astobj2_rwlock *obj_rwlock;
293  struct astobj2_lockobj *obj_lockobj;
294  int res = 0;
295  int current_value;
296 
297  if (obj == NULL) {
298  return -1;
299  }
300 
301  switch (obj->priv_data.options & AO2_ALLOC_OPT_LOCK_MASK) {
303  obj_mutex = INTERNAL_OBJ_MUTEX(user_data);
304  res = __ast_pthread_mutex_unlock(file, line, func, var, &obj_mutex->mutex.lock);
305 #ifdef AO2_DEBUG
306  if (!res) {
307  ast_atomic_fetchadd_int(&ao2.total_locked, -1);
308  }
309 #endif
310  break;
312  obj_rwlock = INTERNAL_OBJ_RWLOCK(user_data);
313 
314  current_value = ast_atomic_fetchadd_int(&obj_rwlock->rwlock.num_lockers, -1) - 1;
315  if (current_value < 0) {
316  /* It was a WRLOCK that we are unlocking. Fix the count. */
317  ast_atomic_fetchadd_int(&obj_rwlock->rwlock.num_lockers, -current_value);
318  }
319  res = __ast_rwlock_unlock(file, line, func, &obj_rwlock->rwlock.lock, var);
320 #ifdef AO2_DEBUG
321  if (!res) {
322  ast_atomic_fetchadd_int(&ao2.total_locked, -1);
323  }
324 #endif
325  break;
327  /* The ao2 object has no lock. */
328  break;
329  case AO2_ALLOC_OPT_LOCK_OBJ:
330  obj_lockobj = INTERNAL_OBJ_LOCKOBJ(user_data);
331  res = __ao2_unlock(obj_lockobj->lockobj.lock, file, func, line, var);
332  break;
333  default:
334  ast_log(__LOG_ERROR, file, line, func, "Invalid lock option on ao2 object %p\n",
335  user_data);
336  res = -1;
337  break;
338  }
339  return res;
340 }
uint32_t options
The ao2 object option flags.
Definition: astobj2.c:70
#define __INTERNAL_OBJ_CHECK(user_data, file, line, func)
convert from a pointer _p to a user-defined object
Definition: astobj2.c:171
int __ao2_unlock(void *user_data, const char *file, const char *func, int line, const char *var)
Unlock an object.
Definition: astobj2.c:288
int ast_atomic_fetchadd_int(volatile int *p, int v)
Atomically add v to *p and return the previous value of *p.
Definition: lock.h:757
int ao2_container_check ( struct ao2_container self,
enum search_flags  flags 
)

Perform an integrity check on the specified container.

Since
12.0.0
Parameters
selfContainer to check integrity.
flagsOBJ_NOLOCK if a lock is already held on the container.
Return values
0on success.
-1on error.

Definition at line 856 of file astobj2_container.c.

857 {
858  int res = 0;
859 
860  if (!is_ao2_object(self) || !self->v_table) {
861  /* Sanity checks. */
862  ast_assert(0);
863  return -1;
864  }
865 #if defined(AO2_DEBUG)
866  if (!self->v_table->integrity) {
867  /* No integrity check available. Assume container is ok. */
868  return 0;
869  }
870 
871  if (!(flags & OBJ_NOLOCK)) {
872  ao2_rdlock(self);
873  }
874  res = self->v_table->integrity(self);
875  if (!(flags & OBJ_NOLOCK)) {
876  ao2_unlock(self);
877  }
878 #endif /* defined(AO2_DEBUG) */
879  return res;
880 }
Assume that the ao2_container is already locked.
Definition: astobj2.h:1063
const struct ao2_container_methods * v_table
int ao2_container_count ( struct ao2_container c)

Returns the number of elements in a container.

return the number of elements in the container

Definition at line 34 of file astobj2_container.c.

References ast_atomic_fetchadd_int(), and ao2_container::elements.

Referenced by ao2_iterator_count(), app_is_finished(), ast_active_channels(), ast_ari_applications_list(), ast_bridge_transfer_attended(), ast_bridge_transfer_blind(), ast_endpoint_snapshot_create(), ast_get_namedgroups(), ast_merge_contexts_and_delete(), ast_namedgroups_intersect(), ast_rtp_ice_add_remote_candidate(), ast_rtp_ice_start(), ast_sorcery_create(), ast_sorcery_delete(), ast_sorcery_retrieve_by_fields(), ast_sorcery_retrieve_by_prefix(), ast_sorcery_retrieve_by_regex(), ast_sorcery_update(), ast_tone_zone_count(), calc_metric(), cli_fax_show_sessions(), control_command_count(), control_wait(), create_sound_blob(), handle_cli_sound_show(), handle_show_hint(), handle_show_hints(), locals_show(), object_type_loaded_observer(), one_protocol(), parking_lot_remove_if_unused(), pjsip_acf_dial_contacts_read(), print_queue(), process_config(), queue_exec(), queue_function_mem_read(), stasis_app_set_global_debug(), stasis_app_to_cli(), test_cel_peer_strings_match(), and unload_module().

35 {
36  return ast_atomic_fetchadd_int(&c->elements, 0);
37 }
int ast_atomic_fetchadd_int(volatile int *p, int v)
Atomically add v to *p and return the previous value of *p.
Definition: lock.h:757
void ao2_container_dump ( struct ao2_container self,
enum search_flags  flags,
const char *  name,
void *  where,
ao2_prnt_fn prnt,
ao2_prnt_obj_fn prnt_obj 
)

Display contents of the specified container.

Since
12.0.0
Parameters
selfContainer to dump.
flagsOBJ_NOLOCK if a lock is already held on the container.
nameContainer name. (NULL if anonymous)
whereUser data needed by prnt to determine where to put output.
prntPrint output callback function to use.
prnt_objCallback function to print the given object's key. (NULL if not available)

Definition at line 792 of file astobj2_container.c.

Referenced by test_traversal_sorted().

793 {
794  if (!is_ao2_object(self) || !self->v_table) {
795  prnt(where, "Invalid container\n");
796  ast_assert(0);
797  return;
798  }
799 
800  if (!(flags & OBJ_NOLOCK)) {
801  ao2_rdlock(self);
802  }
803  if (name) {
804  prnt(where, "Container name: %s\n", name);
805  }
806 #if defined(AO2_DEBUG)
807  if (self->v_table->dump) {
808  self->v_table->dump(self, where, prnt, prnt_obj);
809  } else
810 #endif /* defined(AO2_DEBUG) */
811  {
812  prnt(where, "Container dump not available.\n");
813  }
814  if (!(flags & OBJ_NOLOCK)) {
815  ao2_unlock(self);
816  }
817 }
Assume that the ao2_container is already locked.
Definition: astobj2.h:1063
const struct ao2_container_methods * v_table
int ao2_container_dup ( struct ao2_container dest,
struct ao2_container src,
enum search_flags  flags 
)

Copy all object references in the src container into the dest container.

Since
11.0
Parameters
destContainer to copy src object references into.
srcContainer to copy all object references from.
flagsOBJ_NOLOCK if a lock is already held on both containers. Otherwise, the src container is locked first.
Precondition
The dest container must be empty. If the duplication fails, the dest container will be returned empty.
Note
This can potentially be expensive because a malloc is needed for every object in the src container.
Return values
0on success.
-1on error.

Definition at line 673 of file astobj2_container.c.

References ao2_callback, and OBJ_MULTIPLE.

Referenced by __queues_show(), and handle_cli_sounds_show().

674 {
675  void *obj;
676  int res = 0;
677 
678  if (!(flags & OBJ_NOLOCK)) {
679  ao2_rdlock(src);
680  ao2_wrlock(dest);
681  }
682  obj = ao2_callback(src, OBJ_NOLOCK, dup_obj_cb, dest);
683  if (obj) {
684  /* Failed to put this obj into the dest container. */
685  ao2_t_ref(obj, -1, "Failed to put this object into the dest container.");
686 
687  /* Remove all items from the dest container. */
688  ao2_callback(dest, OBJ_NOLOCK | OBJ_UNLINK | OBJ_NODATA | OBJ_MULTIPLE, NULL,
689  NULL);
690  res = -1;
691  }
692  if (!(flags & OBJ_NOLOCK)) {
693  ao2_unlock(dest);
694  ao2_unlock(src);
695  }
696 
697  return res;
698 }
#define ao2_callback(c, flags, cb_fn, arg)
ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below.
Definition: astobj2.h:1693
Assume that the ao2_container is already locked.
Definition: astobj2.h:1063
int ao2_container_dup_weakproxy_objs ( struct ao2_container dest,
struct ao2_container src,
enum search_flags  flags 
)

Copy object references associated with src container weakproxies into the dest container.

Parameters
destContainer to copy src strong object references into.
srcContainer to copy all weak object references from.
flagsOBJ_NOLOCK if a lock is already held on both containers. Otherwise, the src container is locked first.
Precondition
The dest container must be empty. If the duplication fails, the dest container will be returned empty.
Note
This can potentially be expensive because a malloc is needed for every object in the src container.
Every object inside the container is locked by ao2_weakproxy_get_object. Any weakproxy in src with no associated object is ignored.
Return values
0on success.
-1on error.

Definition at line 726 of file astobj2_container.c.

References ao2_callback, dup_weakproxy_cb(), and OBJ_MULTIPLE.

727 {
728  void *obj;
729  int res = 0;
730 
731  if (!(flags & OBJ_NOLOCK)) {
732  ao2_rdlock(src);
733  ao2_wrlock(dest);
734  }
735  obj = ao2_callback(src, OBJ_NOLOCK, dup_weakproxy_cb, dest);
736  if (obj) {
737  /* Failed to put this obj into the dest container. */
738  ao2_t_ref(obj, -1, "Failed to put this object into the dest container.");
739 
740  /* Remove all items from the dest container. */
741  ao2_callback(dest, OBJ_NOLOCK | OBJ_UNLINK | OBJ_NODATA | OBJ_MULTIPLE, NULL,
742  NULL);
743  res = -1;
744  }
745  if (!(flags & OBJ_NOLOCK)) {
746  ao2_unlock(dest);
747  ao2_unlock(src);
748  }
749 
750  return res;
751 }
#define ao2_callback(c, flags, cb_fn, arg)
ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below.
Definition: astobj2.h:1693
Assume that the ao2_container is already locked.
Definition: astobj2.h:1063
static int dup_weakproxy_cb(void *proxy, void *arg, int flags)
Copy obj associated with a weakproxy into the arg container.
int ao2_container_register ( const char *  name,
struct ao2_container self,
ao2_prnt_obj_fn prnt_obj 
)

Register a container for CLI stats and integrity check.

Since
12.0.0
Parameters
nameName to register the container under.
selfContainer to register.
prnt_objCallback function to print the given object's key. (NULL if not available)
Return values
0on success.
-1on error.

Definition at line 958 of file astobj2_container.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, and ao2_t_alloc_options.

Referenced by ast_bridging_init(), ast_channels_init(), ast_pbx_init(), load_module(), stasis_caching_topic_create(), stasis_state_manager_create(), and stasis_topic_pool_create().

959 {
960  int res = 0;
961 #if defined(AO2_DEBUG)
962  struct ao2_reg_container *reg;
963 
964  reg = ao2_t_alloc_options(sizeof(*reg) + strlen(name), ao2_reg_destructor,
965  AO2_ALLOC_OPT_LOCK_NOLOCK, "Container registration object.");
966  if (!reg) {
967  return -1;
968  }
969 
970  /* Fill in registered entry */
971  ao2_t_ref(self, +1, "Registering container.");
972  reg->registered = self;
973  reg->prnt_obj = prnt_obj;
974  strcpy(reg->name, name);/* safe */
975 
976  if (!ao2_t_link(reg_containers, reg, "Save registration object.")) {
977  res = -1;
978  }
979 
980  ao2_t_ref(reg, -1, "Done registering container.");
981 #endif /* defined(AO2_DEBUG) */
982  return res;
983 }
#define ao2_t_alloc_options(data_size, destructor_fn, options, debug_msg)
Allocate and initialize an object.
Definition: astobj2.h:402
void ao2_container_stats ( struct ao2_container self,
enum search_flags  flags,
const char *  name,
void *  where,
ao2_prnt_fn prnt 
)

Display statistics of the specified container.

Since
12.0.0
Parameters
selfContainer to display statistics.
flagsOBJ_NOLOCK if a lock is already held on the container.
nameContainer name. (NULL if anonymous)
whereUser data needed by prnt to determine where to put output.
prntPrint output callback function to use.

Definition at line 819 of file astobj2_container.c.

Referenced by test_traversal_sorted().

820 {
821  if (!is_ao2_object(self) || !self->v_table) {
822  prnt(where, "Invalid container\n");
823  ast_assert(0);
824  return;
825  }
826 
827  if (!(flags & OBJ_NOLOCK)) {
828  ao2_rdlock(self);
829  }
830  if (name) {
831  prnt(where, "Container name: %s\n", name);
832  }
833  prnt(where, "Number of objects: %d\n", self->elements);
834 #if defined(AO2_DEBUG)
835  prnt(where, "Number of nodes: %d\n", self->nodes);
836  prnt(where, "Number of empty nodes: %d\n", self->nodes - self->elements);
837  /*
838  * XXX
839  * If the max_empty_nodes count gets out of single digits you
840  * likely have a code path where ao2_iterator_destroy() is not
841  * called.
842  *
843  * Empty nodes do not harm the container but they do make
844  * container operations less efficient.
845  */
846  prnt(where, "Maximum empty nodes: %d\n", self->max_empty_nodes);
847  if (self->v_table->stats) {
848  self->v_table->stats(self, where, prnt);
849  }
850 #endif /* defined(AO2_DEBUG) */
851  if (!(flags & OBJ_NOLOCK)) {
852  ao2_unlock(self);
853  }
854 }
Assume that the ao2_container is already locked.
Definition: astobj2.h:1063
const struct ao2_container_methods * v_table
void ao2_container_unregister ( const char *  name)

Unregister a container for CLI stats and integrity check.

Since
12.0.0
Parameters
nameName the container is registered under.

Definition at line 985 of file astobj2_container.c.

References ao2_t_find, and OBJ_SEARCH_KEY.

Referenced by load_module().

986 {
987 #if defined(AO2_DEBUG)
988  ao2_t_find(reg_containers, name, OBJ_UNLINK | OBJ_NODATA | OBJ_SEARCH_KEY,
989  "Unregister container");
990 #endif /* defined(AO2_DEBUG) */
991 }
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
#define ao2_t_find(container, arg, flags, tag)
Definition: astobj2.h:1734
int ao2_iterator_count ( struct ao2_iterator iter)

Get a count of the iterated container objects.

Parameters
iterthe iterator to query
Returns
The number of objects in the iterated container

Definition at line 630 of file astobj2_container.c.

References ao2_container_count(), and ao2_iterator::c.

631 {
632  return ao2_container_count(iter->c);
633 }
int ao2_container_count(struct ao2_container *c)
Returns the number of elements in a container.
struct ao2_container * c
Definition: astobj2.h:1823
void ao2_iterator_destroy ( struct ao2_iterator iter)

Destroy a container iterator.

Parameters
iterthe iterator to destroy

This function will release the container reference held by the iterator and any other resources it may be holding.

Examples:
app_skel.c.

Definition at line 534 of file astobj2_container.c.

References AO2_ITERATOR_MALLOCD, ao2_iterator_restart(), ao2_iterator::c, and ao2_iterator::flags.

Referenced by __queues_show(), aco_set_defaults(), action_coreshowchannelmap(), action_coreshowchannels(), add_ice_to_stream(), alias_show(), app_to_json(), ast_add_hint(), ast_ari_bridges_list(), ast_ari_channels_list(), ast_ari_endpoints_list(), ast_ari_endpoints_list_by_tech(), ast_ari_recordings_list_stored(), ast_bridge_channel_kick(), ast_bucket_file_json(), ast_bucket_json(), ast_cdr_setvar(), ast_channel_iterator_destroy(), ast_complete_channels(), ast_endpoint_snapshot_create(), ast_format_cache_get_by_codec(), ast_merge_contexts_and_delete(), ast_msg_var_iterator_destroy(), ast_multi_channel_blob_get_channels(), ast_pickup_find_by_group(), ast_print_namedgroups(), ast_refer_var_iterator_destroy(), ast_rtp_ice_start(), ast_sorcery_objectset_create2(), ast_sorcery_objectset_json_create(), astman_verify_session_readpermissions(), astman_verify_session_writepermissions(), authenticate_reply(), bridge_app_subscribed_involved(), clear_stats(), cli_complete_show(), cli_fax_show_sessions(), complete_core_show_hint(), complete_mohclass_realtime(), complete_queue(), control_dispatch_all(), control_flush_queue(), control_prestart_dispatch_all(), coreshowchannelmap_add_connected_channels(), device_state_cb(), dump_queue_members(), event_session_shutdown(), fax_session_tab_complete(), find_queue_by_name_rt(), find_session(), find_session_by_nonce(), free_members(), get_member_status(), handle_bridge_pairings(), handle_cli_sound_show(), handle_kickmanconn(), handle_show_calendars(), handle_show_hint(), handle_show_hints(), handle_show_named_acl_cmd(), handle_showmanconn(), handle_voicemail_show_aliases(), jingle_add_google_candidates_to_transport(), jingle_add_ice_udp_candidates_to_transport(), jingle_request(), load_users(), local_devicestate(), locals_show(), manager_iax2_show_peer_list(), manager_queues_status(), manager_queues_summary(), num_available_members(), parking_lot_get_space(), pjsip_acf_dial_contacts_read(), print_queue(), purge_sessions(), queue_function_mem_read(), queue_function_qac_dep(), queue_function_queuememberlist(), qupd_exec(), reload_single_queue(), rt_handle_member_record(), rtp_add_candidates_to_ice(), set_config(), sla_calc_station_delays(), sla_queue_event_conf(), stasis_app_mailboxes_to_json(), stasis_app_to_cli(), update_queue(), and xmpp_pubsub_create_affiliations().

535 {
536  /* Release any last container node reference. */
537  ao2_iterator_restart(iter);
538 
539  /* Release the iterated container reference. */
540  ao2_t_ref(iter->c, -1, "Unref iterator in ao2_iterator_destroy");
541  iter->c = NULL;
542 
543  /* Free the malloced iterator. */
544  if (iter->flags & AO2_ITERATOR_MALLOCD) {
545  ast_free(iter);
546  }
547 }
void ao2_iterator_restart(struct ao2_iterator *iter)
Restart an iteration.
struct ao2_container * c
Definition: astobj2.h:1823
struct ao2_iterator ao2_iterator_init ( struct ao2_container c,
int  flags 
)

Create an iterator for a container.

Parameters
cthe container
flagsone or more flags from ao2_iterator_flags.
Returns
the constructed iterator
Note
This function does not take a pointer to an iterator; rather, it returns an iterator structure that should be assigned to (overwriting) an existing iterator structure allocated on the stack or on the heap.

This function will take a reference on the container being iterated.

initialize an iterator so we start from the first object

Examples:
app_skel.c.

Definition at line 485 of file astobj2_container.c.

References ao2_iterator::c.

Referenced by __queues_show(), aco_set_defaults(), action_coreshowchannelmap(), action_coreshowchannels(), add_ice_to_stream(), alias_show(), app_to_json(), ast_add_hint(), ast_ari_bridges_list(), ast_ari_channels_list(), ast_ari_endpoints_list(), ast_ari_endpoints_list_by_tech(), ast_ari_recordings_list_stored(), ast_bridge_channel_kick(), ast_bucket_file_json(), ast_bucket_json(), ast_channel_iterator_all_new(), ast_complete_channels(), ast_endpoint_snapshot_create(), ast_format_cache_get_by_codec(), ast_merge_contexts_and_delete(), ast_msg_var_iterator_init(), ast_pickup_find_by_group(), ast_print_namedgroups(), ast_refer_var_iterator_init(), ast_rtp_ice_start(), ast_sorcery_objectset_create2(), ast_sorcery_objectset_json_create(), ast_tone_zone_iterator_init(), astman_verify_session_readpermissions(), astman_verify_session_writepermissions(), authenticate_reply(), bridge_app_subscribed_involved(), clear_stats(), cli_complete_show(), cli_fax_show_sessions(), complete_core_show_hint(), complete_mohclass_realtime(), complete_queue(), control_dispatch_all(), control_flush_queue(), control_prestart_dispatch_all(), coreshowchannelmap_add_connected_channels(), device_state_cb(), dump_queue_members(), event_session_shutdown(), fax_session_tab_complete(), find_queue_by_name_rt(), find_session(), find_session_by_nonce(), free_members(), get_member_status(), handle_bridge_pairings(), handle_cli_sound_show(), handle_kickmanconn(), handle_show_calendars(), handle_show_hint(), handle_show_hints(), handle_show_named_acl_cmd(), handle_showmanconn(), handle_voicemail_show_aliases(), jingle_add_google_candidates_to_transport(), jingle_add_ice_udp_candidates_to_transport(), jingle_request(), load_users(), local_devicestate(), locals_show(), manager_iax2_show_peer_list(), manager_queues_status(), manager_queues_summary(), num_available_members(), parking_lot_get_space(), pjsip_acf_dial_contacts_read(), print_queue(), purge_sessions(), queue_function_mem_read(), queue_function_qac_dep(), queue_function_queuememberlist(), qupd_exec(), reload_single_queue(), rt_handle_member_record(), rtp_add_candidates_to_ice(), set_config(), sla_calc_station_delays(), sla_queue_event_conf(), stasis_app_mailboxes_to_json(), stasis_app_set_global_debug(), update_queue(), and xmpp_pubsub_create_affiliations().

486 {
487  struct ao2_iterator a = {
488  .c = c,
489  .flags = flags
490  };
491 
492  ao2_t_ref(c, +1, "Init iterator with container.");
493 
494  return a;
495 }
struct ao2_container * c
Definition: astobj2.h:1823
When we need to walk through a container, we use an ao2_iterator to keep track of the current positio...
Definition: astobj2.h:1821
void ao2_iterator_restart ( struct ao2_iterator iter)

Restart an iteration.

Parameters
iterthe iterator to restart
Note
A restart is not going to have any effect if the iterator was created with the AO2_ITERATOR_UNLINK flag. Any previous objects returned were removed from the container.

Definition at line 497 of file astobj2_container.c.

References AO2_ITERATOR_DONTLOCK, AO2_LOCK_REQ_MUTEX, AO2_LOCK_REQ_RDLOCK, ao2_ref, ao2_iterator::c, ao2_iterator::complete, ao2_iterator::flags, and ao2_iterator::last_node.

Referenced by ao2_iterator_destroy().

498 {
499  if (!is_ao2_object(iter->c)) {
500  /* Sanity check. */
501  return;
502  }
503 
504  /* Release the last container node reference if we have one. */
505  if (iter->last_node) {
506  enum ao2_lock_req orig_lock;
507 
508  /*
509  * Do a read lock in case the container node unref does not
510  * destroy the node. If the container node is destroyed then
511  * the lock will be upgraded to a write lock.
512  */
513  if (iter->flags & AO2_ITERATOR_DONTLOCK) {
514  orig_lock = __adjust_lock(iter->c, AO2_LOCK_REQ_RDLOCK, 1);
515  } else {
516  orig_lock = AO2_LOCK_REQ_MUTEX;
517  ao2_rdlock(iter->c);
518  }
519 
520  ao2_ref(iter->last_node, -1);
521  iter->last_node = NULL;
522 
523  if (iter->flags & AO2_ITERATOR_DONTLOCK) {
524  __adjust_lock(iter->c, orig_lock, 0);
525  } else {
526  ao2_unlock(iter->c);
527  }
528  }
529 
530  /* The iteration is no longer complete. */
531  iter->complete = 0;
532 }
void * last_node
Definition: astobj2.h:1825
ao2_lock_req
Which lock to request.
Definition: astobj2.h:700
int complete
Definition: astobj2.h:1827
struct ao2_container * c
Definition: astobj2.h:1823
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
Assume that the ao2_container is already locked.
Definition: astobj2.h:1852
int ao2_match_by_addr ( void *  user_data,
void *  arg,
int  flags 
)

A common ao2_callback is one that matches by address.

A common ao2_callback is one that matches by address.

Definition at line 166 of file astobj2_container.c.

References CMP_MATCH, and CMP_STOP.

167 {
168  return (user_data == arg) ? (CMP_MATCH | CMP_STOP) : 0;
169 }
void* ao2_object_get_lockaddr ( void *  obj)

Return the mutex lock address of an object.

Parameters
[in]objA pointer to the object we want.
Returns
the address of the mutex lock, else NULL.

This function comes in handy mainly for debugging locking situations, where the locking trace code reports the lock address, this allows you to correlate against object address, to match objects to reported locks.

Warning
AO2 lock objects do not include tracking fields when DEBUG_THREADS is not enabled.
Since
1.6.1

Definition at line 476 of file astobj2.c.

References AO2_ALLOC_OPT_LOCK_MASK, AO2_ALLOC_OPT_LOCK_MUTEX, and __priv_data::options.

Referenced by ast_rtp_ice_turn_request(), control_wait(), db_sync_thread(), ice_reset_session(), and stasis_subscription_join().

477 {
478  struct astobj2 *obj;
479  struct astobj2_lock *obj_mutex;
480 
481  obj = INTERNAL_OBJ_CHECK(user_data);
482 
483  if (obj == NULL) {
484  return NULL;
485  }
486 
487  switch (obj->priv_data.options & AO2_ALLOC_OPT_LOCK_MASK) {
489  obj_mutex = INTERNAL_OBJ_MUTEX(user_data);
490  return &obj_mutex->mutex.lock;
491  default:
492  break;
493  }
494 
495  return NULL;
496 }
uint32_t options
The ao2 object option flags.
Definition: astobj2.c:70
unsigned int ao2_options_get ( void *  obj)

Retrieve the ao2 options used to create the object.

Parameters
objpointer to the (user-defined part) of an object.
Returns
options from enum ao2_alloc_opts.

Definition at line 781 of file astobj2.c.

References __priv_data::options.

782 {
783  struct astobj2 *orig_obj;
784 
785  orig_obj = INTERNAL_OBJ_CHECK(obj);
786  if (!orig_obj) {
787  return 0;
788  }
789  return orig_obj->priv_data.options;
790 }
uint32_t options
The ao2 object option flags.
Definition: astobj2.c:70
int ao2_ref_and_lock ( void *  obj)
inline

Increment reference count on an object and lock it.

Since
13.9.0
Parameters
[in]objA pointer to the ao2 object
Return values
0The object is not an ao2 object or wasn't locked successfully
1The object's reference count was incremented and was locked

Definition at line 780 of file astobj2.h.

References ao2_ref.

792 {
int ao2_unlock_and_unref ( void *  obj)
inline

Unlock an object and decrement its reference count.

Since
13.9.0
Parameters
[in]objA pointer to the ao2 object
Return values
0The object is not an ao2 object or wasn't unlocked successfully
1The object was unlocked and it's reference count was decremented

Definition at line 800 of file astobj2.h.

803 {
int ao2_weakproxy_subscribe ( void *  weakproxy,
ao2_weakproxy_notification_cb  cb,
void *  data,
int  flags 
)

Request notification when weakproxy points to NULL.

Since
14.0.0
Parameters
weakproxyThe weak object
cbProcedure to call when no real object is associated
dataPassed to cb
flagsOBJ_NOLOCK to avoid locking weakproxy.
Return values
0Success
-1Failure
Note
Callbacks are run in the reverse order of subscriptions.
This procedure will allow the same cb / data pair to be added to the same weakproxy multiple times.
It is the caller's responsibility to ensure that *data is valid until after cb() is run or ao2_weakproxy_unsubscribe is called.
If the weakproxy currently points to NULL the callback will be run immediately, without being added to the subscriber list.

Definition at line 934 of file astobj2.c.

References ast_calloc, AST_LIST_INSERT_HEAD, and __priv_data::weakptr.

935 {
936  struct astobj2 *weakproxy_internal = INTERNAL_OBJ_CHECK(weakproxy);
937  int ret = -1;
938  int hasobj;
939 
940  if (!weakproxy_internal || weakproxy_internal->priv_data.magic != AO2_WEAK) {
941  return -1;
942  }
943 
944  if (!(flags & OBJ_NOLOCK)) {
945  ao2_lock(weakproxy);
946  }
947 
948  hasobj = weakproxy_internal->priv_data.weakptr != NULL;
949  if (hasobj) {
950  struct ao2_weakproxy *weak = weakproxy;
951  struct ao2_weakproxy_notification *sub = ast_calloc(1, sizeof(*sub));
952 
953  if (sub) {
954  sub->cb = cb;
955  sub->data = data;
956  AST_LIST_INSERT_HEAD(&weak->destroyed_cb, sub, list);
957  ret = 0;
958  }
959  }
960 
961  if (!(flags & OBJ_NOLOCK)) {
962  ao2_unlock(weakproxy);
963  }
964 
965  if (!hasobj) {
966  cb(weakproxy, data);
967  ret = 0;
968  }
969 
970  return ret;
971 }
Assume that the ao2_container is already locked.
Definition: astobj2.h:1063
void * weakptr
Definition: astobj2.c:57
#define AST_LIST_INSERT_HEAD(head, elm, field)
Inserts a list entry at the head of a list.
Definition: linkedlists.h:711
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
This struct should be opaque, but it's size is needed.
Definition: astobj2.h:529
int ao2_weakproxy_unsubscribe ( void *  weakproxy,
ao2_weakproxy_notification_cb  cb,
void *  data,
int  flags 
)

Remove notification of real object destruction.

Since
14.0.0
Parameters
weakproxyThe weak object
cbCallback to remove from destroy notification list
dataData pointer to match
flagsOBJ_NOLOCK to avoid locking weakproxy. OBJ_MULTIPLE to remove all copies of the same cb / data pair.
Returns
The number of subscriptions removed.
Return values
0cb / data pair not found, nothing removed.
-1Failure due to invalid parameters.
Note
Unless flags includes OBJ_MULTIPLE, this will only remove a single copy of the cb / data pair. If it was subscribed multiple times it must be unsubscribed as many times. The OBJ_MULTIPLE flag can be used to remove matching subscriptions.
When it's time to run callbacks they are copied to a temporary list so the weakproxy can be unlocked before running. That means it's possible for this function to find nothing before the callback is run in another thread.

Definition at line 973 of file astobj2.c.

References AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, and OBJ_MULTIPLE.

974 {
975  struct astobj2 *internal_weakproxy = INTERNAL_OBJ_CHECK(weakproxy);
976  struct ao2_weakproxy *weak;
977  struct ao2_weakproxy_notification *sub;
978  int ret = 0;
979 
980  if (!internal_weakproxy || internal_weakproxy->priv_data.magic != AO2_WEAK || !destroyed_cb) {
981  return -1;
982  }
983 
984  if (!(flags & OBJ_NOLOCK)) {
985  ao2_lock(weakproxy);
986  }
987 
988  weak = weakproxy;
989  AST_LIST_TRAVERSE_SAFE_BEGIN(&weak->destroyed_cb, sub, list) {
990  if (sub->cb == destroyed_cb && sub->data == data) {
992  ast_free(sub);
993  ret++;
994  if (!(flags & OBJ_MULTIPLE)) {
995  break;
996  }
997  }
998  }
1000 
1001  if (!(flags & OBJ_NOLOCK)) {
1002  ao2_unlock(weakproxy);
1003  }
1004 
1005  return ret;
1006 }
Assume that the ao2_container is already locked.
Definition: astobj2.h:1063
#define AST_LIST_TRAVERSE_SAFE_END
Closes a safe loop traversal block.
Definition: linkedlists.h:615
#define AST_LIST_REMOVE_CURRENT(field)
Removes the current entry from a list during a traversal.
Definition: linkedlists.h:557
This struct should be opaque, but it's size is needed.
Definition: astobj2.h:529
#define AST_LIST_TRAVERSE_SAFE_BEGIN(head, var, field)
Loops safely over (traverses) the entries in a list.
Definition: linkedlists.h:529