Asterisk - The Open Source Telephony Project  GIT-master-93d0901
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"
Include dependency graph for astobj2.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...
 
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_alloc(data_size, destructor_fn)    __ao2_alloc((data_size), (destructor_fn), AO2_ALLOC_OPT_LOCK_MUTEX, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#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_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...
 
int __ao2_ref (void *o, int delta, const char *tag, const char *file, int line, const char *func)
 
#define ao2_bump(obj)    ao2_t_bump((obj), NULL)
 Bump refcount on an AO2 object by one, returning the object. More...
 
unsigned int ao2_options_get (void *obj)
 Retrieve the ao2 options used to create the object. More...
 
#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_replace(dst, src)    ao2_t_replace((dst), (src), NULL)
 Replace one object reference with another cleaning up the original. More...
 
#define ao2_t_bump(obj, tag)
 
#define ao2_t_ref(o, delta, tag)   __ao2_ref((o), (delta), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_t_replace(dst, src, tag)
 
void * __ao2_get_weakproxy (void *obj, const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result
 
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
 
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_ref_object (void *weakproxy, int delta, int flags, const char *tag, const char *file, int line, const char *func)
 
int __ao2_weakproxy_set_object (void *weakproxy, void *obj, int flags, const char *tag, const char *file, int line, const char *func)
 
#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__)
 
#define ao2_t_weakproxy_alloc(data_size, destructor_fn, tag)    __ao2_weakproxy_alloc(data_size, destructor_fn, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_t_weakproxy_get_object(weakproxy, flags, tag)    __ao2_weakproxy_get_object(weakproxy, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_t_weakproxy_ref_object(weakproxy, delta, flags, tag)
 
#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()   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_weakproxy_get_object(weakproxy, flags)    __ao2_weakproxy_get_object(weakproxy, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Get the object associated with weakproxy. More...
 
typedef void(* ao2_weakproxy_notification_cb) (void *weakproxy, void *data)
 
#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_weakproxy_set_object(weakproxy, obj, flags)    __ao2_weakproxy_set_object(weakproxy, obj, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Associate weakproxy with obj. More...
 
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...
 

Object Containers

Here start declarations of containers.

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
 
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
 
#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_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_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...
 
int ao2_container_check (struct ao2_container *self, enum search_flags flags)
 Perform an integrity check on the specified container. More...
 
#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...
 
int ao2_container_count (struct ao2_container *c)
 Returns the number of elements in a container. More...
 
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...
 
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...
 
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_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...
 
void ao2_container_unregister (const char *name)
 Unregister a container for CLI stats and integrity check. More...
 
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...
 
#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_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_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_t_container_clone(orig, flags, tag)    __ao2_container_clone(orig, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 

Object Management

Here we have functions to manage objects.

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

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_link(container, obj)    __ao2_link((container), (obj), 0, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Add an object to a container. More...
 
#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(container, obj, tag)    __ao2_link((container), (obj), 0, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_t_link_flags(container, obj, flags, tag)    __ao2_link((container), (obj), (flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_t_unlink(container, obj, tag)    __ao2_unlink((container), (obj), 0, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_t_unlink_flags(container, obj, flags, tag)    __ao2_unlink((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_unlink_flags(container, obj, flags)    __ao2_unlink((container), (obj), (flags), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Remove an object from a container. More...
 
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)
 
#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__)
 

Detailed Description

Object Model implementing objects and containers.

Definition in file astobj2.h.

Macro Definition Documentation

◆ ao2_alloc

#define ao2_alloc (   data_size,
  destructor_fn 
)     __ao2_alloc((data_size), (destructor_fn), AO2_ALLOC_OPT_LOCK_MUTEX, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
Examples
app_skel.c.

Definition at line 409 of file astobj2.h.

◆ ao2_alloc_options

#define ao2_alloc_options (   data_size,
  destructor_fn,
  options 
)     __ao2_alloc((data_size), (destructor_fn), (options), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 404 of file astobj2.h.

◆ ao2_alloc_with_lockobj

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

◆ ao2_bump

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

◆ ao2_callback

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

◆ ao2_callback_data

#define ao2_callback_data (   container,
  flags,
  cb_fn,
  arg,
  data 
)     __ao2_callback_data((container), (flags), (cb_fn), (arg), (data), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 1723 of file astobj2.h.

◆ ao2_cleanup

#define ao2_cleanup (   obj)    __ao2_cleanup_debug((obj), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
Examples
app_skel.c.

Definition at line 1934 of file astobj2.h.

◆ ao2_container_alloc_hash

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

◆ ao2_container_alloc_list

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

◆ ao2_container_alloc_rbtree

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

◆ ao2_container_clone

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

◆ AO2_FIELD_CMP_FN

#define AO2_FIELD_CMP_FN (   stype,
  fn_suffix,
  field,
  key_cmp,
  partial_key_cmp,
  transform,
  argconst 
)

Definition at line 1999 of file astobj2.h.

◆ AO2_FIELD_HASH_FN

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

◆ AO2_FIELD_TRANSFORM_CMP_FN

#define AO2_FIELD_TRANSFORM_CMP_FN (   cmp)    ((cmp) ? 0 : CMP_MATCH)

Definition at line 1977 of file astobj2.h.

◆ AO2_FIELD_TRANSFORM_SORT_FN

#define AO2_FIELD_TRANSFORM_SORT_FN (   cmp)    (cmp)

Definition at line 1978 of file astobj2.h.

◆ ao2_find

#define ao2_find (   container,
  arg,
  flags 
)     __ao2_find((container), (arg), (flags), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
Examples
app_skel.c.

Definition at line 1736 of file astobj2.h.

◆ ao2_get_weakproxy

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

◆ ao2_global_obj_ref

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

◆ ao2_global_obj_release

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

◆ ao2_global_obj_replace

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

◆ ao2_global_obj_replace_unref

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

◆ AO2_GLOBAL_OBJ_STATIC

#define AO2_GLOBAL_OBJ_STATIC (   name)
Value:
struct ao2_global_obj name = { \
}
static const char name[]
Definition: format_mp3.c:68
#define AST_RWLOCK_INIT_VALUE
Definition: lock.h:98

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:

static AO2_GLOBAL_OBJ_STATIC(global_cfg);
#define AO2_GLOBAL_OBJ_STATIC(name)
Define a global object holder to be used to hold an ao2 object, statically initialized.
Definition: astobj2.h:847

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

Definition at line 847 of file astobj2.h.

◆ ao2_iterator_next

#define ao2_iterator_next (   iter)     __ao2_iterator_next((iter), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
Examples
app_skel.c.

Definition at line 1911 of file astobj2.h.

◆ ao2_link

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

◆ ao2_link_flags

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

◆ ao2_lock

#define ao2_lock (   a)    __ao2_lock(a, AO2_LOCK_REQ_MUTEX, __FILE__, __PRETTY_FUNCTION__, __LINE__, #a)
Examples
app_skel.c.

Definition at line 717 of file astobj2.h.

◆ ao2_rdlock

#define ao2_rdlock (   a)    __ao2_lock(a, AO2_LOCK_REQ_RDLOCK, __FILE__, __PRETTY_FUNCTION__, __LINE__, #a)

Definition at line 718 of file astobj2.h.

◆ ao2_ref

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

◆ ao2_replace

#define ao2_replace (   dst,
  src 
)     ao2_t_replace((dst), (src), NULL)

Replace one object reference with another cleaning up the original.

Since
12.4.0
Parameters
dstPointer to the object that will be cleaned up.
srcPointer to the object replacing it.

Definition at line 501 of file astobj2.h.

◆ AO2_STRING_FIELD_CASE_CMP_FN

#define AO2_STRING_FIELD_CASE_CMP_FN (   stype,
  field 
)     AO2_FIELD_CMP_FN(stype, _cmp_fn, field, strcasecmp, strncasecmp, AO2_FIELD_TRANSFORM_CMP_FN,)

Definition at line 2050 of file astobj2.h.

◆ AO2_STRING_FIELD_CASE_HASH_FN

#define AO2_STRING_FIELD_CASE_HASH_FN (   stype,
  field 
)     AO2_FIELD_HASH_FN(stype, field, ast_str_case_hash)

Definition at line 2034 of file astobj2.h.

◆ AO2_STRING_FIELD_CASE_SORT_FN

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

Definition at line 2066 of file astobj2.h.

◆ AO2_STRING_FIELD_CMP_FN

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

◆ AO2_STRING_FIELD_HASH_FN

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

◆ AO2_STRING_FIELD_SORT_FN

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

◆ ao2_t_alloc

#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__)

Definition at line 407 of file astobj2.h.

◆ ao2_t_alloc_options

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

◆ ao2_t_bump

#define ao2_t_bump (   obj,
  tag 
)

Definition at line 483 of file astobj2.h.

◆ ao2_t_callback

#define ao2_t_callback (   c,
  flags,
  cb_fn,
  arg,
  tag 
)     __ao2_callback((c), (flags), (cb_fn), (arg), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 1696 of file astobj2.h.

◆ ao2_t_callback_data

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

◆ ao2_t_cleanup

#define ao2_t_cleanup (   obj,
  tag 
)    __ao2_cleanup_debug((obj), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 1935 of file astobj2.h.

◆ ao2_t_container_alloc_hash

#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__)

Definition at line 1306 of file astobj2.h.

◆ ao2_t_container_alloc_list

#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__)

Definition at line 1330 of file astobj2.h.

◆ ao2_t_container_alloc_rbtree

#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__)

Definition at line 1352 of file astobj2.h.

◆ ao2_t_container_clone

#define ao2_t_container_clone (   orig,
  flags,
  tag 
)     __ao2_container_clone(orig, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 1422 of file astobj2.h.

◆ ao2_t_find

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

◆ ao2_t_get_weakproxy

#define ao2_t_get_weakproxy (   obj,
  tag 
)     __ao2_get_weakproxy(obj, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 691 of file astobj2.h.

◆ ao2_t_global_obj_ref

#define ao2_t_global_obj_ref (   holder,
  tag 
)     __ao2_global_obj_ref(&holder, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)

Definition at line 921 of file astobj2.h.

◆ ao2_t_global_obj_release

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

Definition at line 861 of file astobj2.h.

◆ ao2_t_global_obj_replace

#define ao2_t_global_obj_replace (   holder,
  obj,
  tag 
)     __ao2_global_obj_replace(&holder, (obj), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)

Definition at line 881 of file astobj2.h.

◆ ao2_t_global_obj_replace_unref

#define ao2_t_global_obj_replace_unref (   holder,
  obj,
  tag 
)     __ao2_global_obj_replace_unref(&holder, (obj), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)

Definition at line 904 of file astobj2.h.

◆ ao2_t_iterator_next

#define ao2_t_iterator_next (   iter,
  tag 
)     __ao2_iterator_next((iter), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 1909 of file astobj2.h.

◆ ao2_t_link

#define ao2_t_link (   container,
  obj,
  tag 
)     __ao2_link((container), (obj), 0, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 1534 of file astobj2.h.

◆ ao2_t_link_flags

#define ao2_t_link_flags (   container,
  obj,
  flags,
  tag 
)     __ao2_link((container), (obj), (flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 1556 of file astobj2.h.

◆ ao2_t_ref

#define ao2_t_ref (   o,
  delta,
  tag 
)    __ao2_ref((o), (delta), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 460 of file astobj2.h.

◆ ao2_t_replace

#define ao2_t_replace (   dst,
  src,
  tag 
)

Definition at line 504 of file astobj2.h.

◆ ao2_t_unlink

#define ao2_t_unlink (   container,
  obj,
  tag 
)     __ao2_unlink((container), (obj), 0, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 1580 of file astobj2.h.

◆ ao2_t_unlink_flags

#define ao2_t_unlink_flags (   container,
  obj,
  flags,
  tag 
)     __ao2_unlink((container), (obj), (flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 1603 of file astobj2.h.

◆ ao2_t_weakproxy_alloc

#define ao2_t_weakproxy_alloc (   data_size,
  destructor_fn,
  tag 
)     __ao2_weakproxy_alloc(data_size, destructor_fn, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 553 of file astobj2.h.

◆ ao2_t_weakproxy_get_object

#define ao2_t_weakproxy_get_object (   weakproxy,
  flags,
  tag 
)     __ao2_weakproxy_get_object(weakproxy, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 624 of file astobj2.h.

◆ ao2_t_weakproxy_ref_object

#define ao2_t_weakproxy_ref_object (   weakproxy,
  delta,
  flags,
  tag 
)
Value:
__ao2_weakproxy_ref_object(weakproxy, delta, flags, \
tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
int __ao2_weakproxy_ref_object(void *weakproxy, int delta, int flags, const char *tag, const char *file, int line, const char *func)
Definition: astobj2.c:862

Definition at line 604 of file astobj2.h.

◆ ao2_t_weakproxy_set_object

#define ao2_t_weakproxy_set_object (   weakproxy,
  obj,
  flags,
  tag 
)     __ao2_weakproxy_set_object(weakproxy, obj, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 582 of file astobj2.h.

◆ ao2_trylock

#define ao2_trylock (   a)    __ao2_trylock(a, AO2_LOCK_REQ_MUTEX, __FILE__, __PRETTY_FUNCTION__, __LINE__, #a)

Definition at line 739 of file astobj2.h.

◆ ao2_tryrdlock

#define ao2_tryrdlock (   a)    __ao2_trylock(a, AO2_LOCK_REQ_RDLOCK, __FILE__, __PRETTY_FUNCTION__, __LINE__, #a)

Definition at line 740 of file astobj2.h.

◆ ao2_trywrlock

#define ao2_trywrlock (   a)    __ao2_trylock(a, AO2_LOCK_REQ_WRLOCK, __FILE__, __PRETTY_FUNCTION__, __LINE__, #a)

Definition at line 741 of file astobj2.h.

◆ ao2_unlink

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

◆ ao2_unlink_flags

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

◆ ao2_unlock

#define ao2_unlock (   a)    __ao2_unlock(a, __FILE__, __PRETTY_FUNCTION__, __LINE__, #a)
Examples
app_skel.c.

Definition at line 729 of file astobj2.h.

◆ AO2_WEAKPROXY

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

◆ ao2_weakproxy_alloc

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

◆ ao2_weakproxy_find

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

◆ ao2_weakproxy_get_object

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

◆ ao2_weakproxy_ref_object

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

◆ ao2_weakproxy_set_object

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

◆ ao2_wrlock

#define ao2_wrlock (   a)    __ao2_lock(a, AO2_LOCK_REQ_WRLOCK, __FILE__, __PRETTY_FUNCTION__, __LINE__, #a)

Definition at line 719 of file astobj2.h.

◆ OBJ_KEY

#define OBJ_KEY   OBJ_SEARCH_KEY

Deprecated name

Examples
app_skel.c.

Definition at line 1151 of file astobj2.h.

◆ OBJ_PARTIAL_KEY

#define OBJ_PARTIAL_KEY   OBJ_SEARCH_PARTIAL_KEY

Deprecated name

Definition at line 1152 of file astobj2.h.

◆ OBJ_POINTER

#define OBJ_POINTER   OBJ_SEARCH_OBJECT

Deprecated name

Definition at line 1150 of file astobj2.h.

Typedef Documentation

◆ ao2_callback_data_fn

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.

◆ ao2_callback_fn

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.

◆ ao2_destructor_fn

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.

◆ ao2_hash_fn

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.

◆ ao2_prnt_fn

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.

◆ ao2_prnt_obj_fn

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.

◆ ao2_sort_fn

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.

◆ ao2_weakproxy_notification_cb

typedef void(* ao2_weakproxy_notification_cb) (void *weakproxy, void *data)

Definition at line 526 of file astobj2.h.

Enumeration Type Documentation

◆ _cb_results

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 };
@ CMP_MATCH
Definition: astobj2.h:1027
@ CMP_STOP
Definition: astobj2.h:1028

◆ ao2_alloc_opts

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_LOCK_OBJ 
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  */
377  /*! The ao2 object will not record any REF_DEBUG entries */
378  AO2_ALLOC_OPT_NO_REF_DEBUG = (1 << 2),
379 };
@ AO2_ALLOC_OPT_LOCK_NOLOCK
Definition: astobj2.h:367
@ AO2_ALLOC_OPT_LOCK_OBJ
Definition: astobj2.h:376
@ AO2_ALLOC_OPT_LOCK_RWLOCK
Definition: astobj2.h:365
@ AO2_ALLOC_OPT_LOCK_MUTEX
Definition: astobj2.h:363
@ AO2_ALLOC_OPT_LOCK_MASK
Definition: astobj2.h:369
@ AO2_ALLOC_OPT_NO_REF_DEBUG
Definition: astobj2.h:378

◆ ao2_container_opts

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 };
@ AO2_CONTAINER_ALLOC_OPT_DUPS_OBJ_REJECT
Reject duplicate objects in container.
Definition: astobj2.h:1201
@ AO2_CONTAINER_ALLOC_OPT_INSERT_BEGIN
Insert objects at the beginning of the container. (Otherwise it is the opposite; insert at the end....
Definition: astobj2.h:1172
@ AO2_CONTAINER_ALLOC_OPT_DUPS_ALLOW
Allow objects with duplicate keys in container.
Definition: astobj2.h:1181
@ AO2_CONTAINER_ALLOC_OPT_DUPS_REJECT
Reject objects with duplicate keys in container.
Definition: astobj2.h:1188
@ AO2_CONTAINER_ALLOC_OPT_DUPS_REPLACE
Replace objects with duplicate keys in container.
Definition: astobj2.h:1211
@ AO2_CONTAINER_ALLOC_OPT_DUPS_MASK
The ao2 container objects with duplicate keys option field mask.
Definition: astobj2.h:1177

◆ ao2_iterator_flags

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 };
@ AO2_ITERATOR_UNLINK
Definition: astobj2.h:1863
@ AO2_ITERATOR_DONTLOCK
Assume that the ao2_container is already locked.
Definition: astobj2.h:1852
@ AO2_ITERATOR_MALLOCD
Definition: astobj2.h:1857
@ AO2_ITERATOR_DESCENDING
Definition: astobj2.h:1875

◆ ao2_lock_req

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 };
@ AO2_LOCK_REQ_MUTEX
Definition: astobj2.h:702
@ AO2_LOCK_REQ_WRLOCK
Definition: astobj2.h:706
@ AO2_LOCK_REQ_RDLOCK
Definition: astobj2.h:704

◆ search_flags

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 };
@ OBJ_ORDER_MASK
Traverse order option field mask.
Definition: astobj2.h:1119
@ OBJ_SEARCH_PARTIAL_KEY
The arg parameter is a partial search key similar to OBJ_SEARCH_KEY.
Definition: astobj2.h:1116
@ OBJ_ORDER_DESCENDING
Traverse in descending order (Last to first container object)
Definition: astobj2.h:1123
@ OBJ_SEARCH_OBJECT
The arg parameter is an object of the same type.
Definition: astobj2.h:1087
@ OBJ_ORDER_PRE
Traverse in pre-order (Node then children, for tree container)
Definition: astobj2.h:1132
@ OBJ_ORDER_ASCENDING
Traverse in ascending order (First to last container object)
Definition: astobj2.h:1121
@ OBJ_NOLOCK
Assume that the ao2_container is already locked.
Definition: astobj2.h:1063
@ OBJ_NODATA
Definition: astobj2.h:1044
@ OBJ_SEARCH_MASK
Search option field mask.
Definition: astobj2.h:1072
@ OBJ_MULTIPLE
Definition: astobj2.h:1049
@ OBJ_UNLINK
Definition: astobj2.h:1039
@ OBJ_ORDER_POST
Traverse in post-order (Children then node, for tree container)
Definition: astobj2.h:1141
@ OBJ_SEARCH_KEY
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
@ OBJ_SEARCH_NONE
The arg parameter has no meaning to the astobj2 code.
Definition: astobj2.h:1074

Function Documentation

◆ __ao2_alloc()

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 
)

Definition at line 768 of file astobj2.c.

770 {
771  return internal_ao2_alloc(data_size, destructor_fn, options, NULL, tag, file, line, func);
772 }
static void * internal_ao2_alloc(size_t data_size, ao2_destructor_fn destructor_fn, unsigned int options, void *lockobj, const char *tag, const char *file, int line, const char *func)
Definition: astobj2.c:684
#define NULL
Definition: resample.c:96
static struct test_options options

References make_ari_stubs::file, internal_ao2_alloc(), NULL, and options.

Referenced by __ao2_container_alloc_hash(), __ao2_weakproxy_alloc(), __ast_channel_internal_alloc(), __ast_format_cap_alloc(), __ast_named_lock_get(), __ast_sorcery_open(), __sip_alloc(), _moh_class_malloc(), and state_alloc().

◆ __ao2_alloc_with_lockobj()

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 
)

Definition at line 774 of file astobj2.c.

776 {
777  return internal_ao2_alloc(data_size, destructor_fn, AO2_ALLOC_OPT_LOCK_OBJ, lockobj,
778  tag, file, line, func);
779 }

References AO2_ALLOC_OPT_LOCK_OBJ, make_ari_stubs::file, and internal_ao2_alloc().

◆ __ao2_callback()

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 
)

Definition at line 410 of file astobj2_container.c.

413 {
414  return internal_ao2_traverse(c, flags, cb_fn, arg, NULL, AO2_CALLBACK_DEFAULT, tag, file, line, func);
415 }
static void * internal_ao2_traverse(struct ao2_container *self, enum search_flags flags, void *cb_fn, void *arg, void *data, enum ao2_callback_type type, const char *tag, const char *file, int line, const char *func)
@ AO2_CALLBACK_DEFAULT
static struct test_val c

References AO2_CALLBACK_DEFAULT, c, make_ari_stubs::file, ao2_iterator::flags, internal_ao2_traverse(), and NULL.

Referenced by __ao2_find(), __ao2_unlink(), and __find_call().

◆ __ao2_callback_data()

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 
)

Definition at line 417 of file astobj2_container.c.

420 {
421  return internal_ao2_traverse(c, flags, cb_fn, arg, data, AO2_CALLBACK_WITH_DATA, tag, file, line, func);
422 }
@ AO2_CALLBACK_WITH_DATA

References AO2_CALLBACK_WITH_DATA, c, make_ari_stubs::file, ao2_iterator::flags, and internal_ao2_traverse().

◆ __ao2_cleanup()

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.

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

References ao2_ref.

Referenced by agent_request_exec(), ast_ari_bridges_set_video_source(), bridge_agent_hold_push(), bridge_builtin_set_limits(), bridge_stasis_queue_join_action(), dial_bridge_after_cb(), internal_bridge_after_cb(), native_rtp_bridge_framehook_attach(), and parking_set_duration().

◆ __ao2_cleanup_debug()

void __ao2_cleanup_debug ( void *  obj,
const char *  tag,
const char *  file,
int  line,
const char *  function 
)

Definition at line 670 of file astobj2.c.

671 {
672  if (obj) {
673  __ao2_ref(obj, -1, tag, file, line, function);
674  }
675 }
int __ao2_ref(void *user_data, int delta, const char *tag, const char *file, int line, const char *func)
Definition: astobj2.c:498

References __ao2_ref(), and make_ari_stubs::file.

◆ __ao2_container_alloc_hash()

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 
)

Definition at line 1067 of file astobj2_hash.c.

1071 {
1072  unsigned int num_buckets;
1073  size_t container_size;
1074  struct ao2_container_hash *self;
1075 
1076  num_buckets = hash_fn ? n_buckets : 1;
1077  container_size = sizeof(struct ao2_container_hash) + num_buckets * sizeof(struct hash_bucket);
1078 
1079  self = __ao2_alloc(container_size, container_destruct, ao2_options,
1080  tag ?: __PRETTY_FUNCTION__, file, line, func);
1081  return hash_ao2_container_init(self, container_options, num_buckets, hash_fn,
1082  sort_fn, cmp_fn);
1083 }
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
Definition: astobj2.c:768
void container_destruct(void *_c)
static struct ao2_container * hash_ao2_container_init(struct ao2_container_hash *self, unsigned int options, unsigned int n_buckets, ao2_hash_fn *hash_fn, ao2_sort_fn *sort_fn, ao2_callback_fn *cmp_fn)
Initialize a hash container with the desired number of buckets.
ao2_hash_fn * hash_fn
Definition: astobj2_hash.c:71

References __ao2_alloc(), container_destruct(), make_ari_stubs::file, hash_ao2_container_init(), ao2_container_hash::hash_fn, and ao2_container_hash::n_buckets.

Referenced by hash_ao2_alloc_empty_clone().

◆ __ao2_container_alloc_list()

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 
)

Definition at line 1085 of file astobj2_hash.c.

1088 {
1089  return __ao2_container_alloc_hash(ao2_options, container_options, 1, NULL,
1090  sort_fn, cmp_fn, tag, file, line, func);
1091 }
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)

◆ __ao2_container_alloc_rbtree()

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 
)

Definition at line 2022 of file astobj2_rbtree.c.

2025 {
2026  struct ao2_container_rbtree *self;
2027 
2028  if (!sort_fn) {
2029  /* Sanity checks. */
2030  ast_log(__LOG_ERROR, file, line, func, "Missing sort_fn()!\n");
2031  return NULL;
2032  }
2033 
2034  self = __ao2_alloc(sizeof(*self), container_destruct, ao2_options,
2035  tag ?: __PRETTY_FUNCTION__, file, line, func);
2036  return rb_ao2_container_init(self, container_options, sort_fn, cmp_fn);
2037 }
#define ast_log
Definition: astobj2.c:42
static struct ao2_container * rb_ao2_container_init(struct ao2_container_rbtree *self, unsigned int options, ao2_sort_fn *sort_fn, ao2_callback_fn *cmp_fn)
Initialize a rbtree container.
#define __LOG_ERROR
Definition: logger.h:285

Referenced by rb_ao2_alloc_empty_clone().

◆ __ao2_container_clone()

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 
)

Definition at line 753 of file astobj2_container.c.

754 {
755  struct ao2_container *clone;
756  int failed;
757 
758  /* Create the clone container with the same properties as the original. */
759  if (!__is_ao2_object(orig, file, line, func)) {
760  return NULL;
761  }
762 
763  if (!orig->v_table || !orig->v_table->alloc_empty_clone) {
764  /* Sanity checks. */
765  __ast_assert_failed(0, "invalid container v_table", file, line, func);
766  return NULL;
767  }
768 
769  clone = orig->v_table->alloc_empty_clone(orig, tag, file, line, func);
770  if (!clone) {
771  return NULL;
772  }
773 
774  /* This test is correct. clone must be locked before calling
775  * ao2_container_dup when the OBJ_NOLOCK flag is set, otherwise
776  * we could have errors in __adjust_lock. */
777  if (flags & OBJ_NOLOCK) {
778  ao2_wrlock(clone);
779  }
780  failed = ao2_container_dup(clone, orig, flags);
781  if (flags & OBJ_NOLOCK) {
782  ao2_unlock(clone);
783  }
784  if (failed) {
785  /* Object copy into the clone container failed. */
786  __ao2_ref(clone, -1, tag ?: "Clone creation failed", file, line, func);
787  clone = NULL;
788  }
789  return clone;
790 }
#define ao2_wrlock(a)
Definition: astobj2.h:719
#define ao2_unlock(a)
Definition: astobj2.h:729
int __ao2_ref(void *o, int delta, const char *tag, const char *file, int line, const char *func)
Definition: astobj2.c:498
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.
#define __is_ao2_object(user_data, file, line, func)
ao2_container_alloc_empty_clone_fn alloc_empty_clone
Create an empty copy of this container.
Generic container type.
const struct ao2_container_methods * v_table
void DO_CRASH_NORETURN __ast_assert_failed(int condition, const char *condition_str, const char *file, int line, const char *function)
Definition: main/utils.c:2712

References __ao2_ref(), __ast_assert_failed(), __is_ao2_object, ao2_container_methods::alloc_empty_clone, ao2_container_dup(), ao2_unlock, ao2_wrlock, make_ari_stubs::file, NULL, OBJ_NOLOCK, and ao2_container::v_table.

◆ __ao2_find()

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.

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 }
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)
#define ast_assert(a)
Definition: utils.h:734

References __ao2_callback(), ast_assert, c, make_ari_stubs::file, ao2_iterator::flags, and NULL.

Referenced by __ast_format_cache_get(), __find_call(), and _get_mohbyname().

◆ __ao2_get_weakproxy()

void* __ao2_get_weakproxy ( void *  obj,
const char *  tag,
const char *  file,
int  line,
const char *  func 
)

Definition at line 917 of file astobj2.c.

918 {
919  struct astobj2 *obj_internal = __INTERNAL_OBJ_CHECK(obj, file, line, func);
920 
921  if (!obj_internal || obj_internal->priv_data.magic != AO2_MAGIC) {
922  /* This method is meant to be run on normal ao2 objects! */
923  return NULL;
924  }
925 
926  if (!obj_internal->priv_data.weakptr) {
927  return NULL;
928  }
929 
930  __ao2_ref(obj_internal->priv_data.weakptr, +1, tag, file, line, func);
931  return obj_internal->priv_data.weakptr;
932 }
#define __INTERNAL_OBJ_CHECK(user_data, file, line, func)
convert from a pointer _p to a user-defined object
Definition: astobj2.c:171
#define AO2_MAGIC
Definition: astobj2.c:96
uint32_t magic
Definition: astobj2.c:93
void * weakptr
Definition: astobj2.c:57
struct __priv_data priv_data
Definition: astobj2.c:105

References __ao2_ref(), __INTERNAL_OBJ_CHECK, AO2_MAGIC, make_ari_stubs::file, __priv_data::magic, NULL, astobj2::priv_data, and __priv_data::weakptr.

◆ __ao2_global_obj_ref()

void* __ao2_global_obj_ref ( struct ao2_global_obj holder,
const char *  tag,
const char *  file,
int  line,
const char *  func,
const char *  name 
)

Definition at line 72 of file astobj2_global.c.

73 {
74  void *obj;
75 
76  if (!holder) {
77  /* For sanity */
78  ast_log(LOG_ERROR, "Must be called with a global object!\n");
79  ast_assert(0);
80  return NULL;
81  }
82 
83  if (__ast_rwlock_rdlock(file, line, func, &holder->lock, name)) {
84  /* Could not get the read lock. */
85  ast_assert(0);
86  return NULL;
87  }
88 
89  obj = holder->obj;
90  if (obj) {
91  __ao2_ref(obj, +1, tag, file, line, func);
92  }
93 
94  __ast_rwlock_unlock(file, line, func, &holder->lock, name);
95 
96  return obj;
97 }
int __ast_rwlock_unlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name)
Definition: lock.c:748
int __ast_rwlock_rdlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name)
Definition: lock.c:819
#define LOG_ERROR
Definition: logger.h:286
void * obj
Definition: astobj2.h:807
ast_rwlock_t lock
Definition: astobj2.h:805

References __ao2_ref(), __ast_rwlock_rdlock(), __ast_rwlock_unlock(), ast_assert, ast_log, make_ari_stubs::file, ao2_global_obj::lock, LOG_ERROR, name, NULL, and ao2_global_obj::obj.

◆ __ao2_global_obj_replace()

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 
)

Definition at line 33 of file astobj2_global.c.

34 {
35  void *obj_old;
36 
37  if (!holder) {
38  /* For sanity */
39  ast_log(LOG_ERROR, "Must be called with a global object!\n");
40  ast_assert(0);
41  return NULL;
42  }
43  if (__ast_rwlock_wrlock(file, line, func, &holder->lock, name)) {
44  /* Could not get the write lock. */
45  ast_assert(0);
46  return NULL;
47  }
48 
49  if (obj) {
50  __ao2_ref(obj, +1, tag, file, line, func);
51  }
52  obj_old = holder->obj;
53  holder->obj = obj;
54 
55  __ast_rwlock_unlock(file, line, func, &holder->lock, name);
56 
57  return obj_old;
58 }
int __ast_rwlock_wrlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name)
Definition: lock.c:917

References __ao2_ref(), __ast_rwlock_unlock(), __ast_rwlock_wrlock(), ast_assert, ast_log, make_ari_stubs::file, ao2_global_obj::lock, LOG_ERROR, name, NULL, and ao2_global_obj::obj.

Referenced by __ao2_global_obj_replace_unref().

◆ __ao2_global_obj_replace_unref()

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 
)

Definition at line 60 of file astobj2_global.c.

61 {
62  void *obj_old;
63 
64  obj_old = __ao2_global_obj_replace(holder, obj, tag, file, line, func, name);
65  if (obj_old) {
66  __ao2_ref(obj_old, -1, tag, file, line, func);
67  return 1;
68  }
69  return 0;
70 }
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)

References __ao2_global_obj_replace(), __ao2_ref(), make_ari_stubs::file, and name.

◆ __ao2_iterator_next()

void* __ao2_iterator_next ( struct ao2_iterator iter,
const char *  tag,
const char *  file,
int  line,
const char *  func 
)

Definition at line 556 of file astobj2_container.c.

558 {
559  enum ao2_lock_req orig_lock;
560  struct ao2_container_node *node;
561  void *ret;
562 
563  if (!__is_ao2_object(iter->c, file, line, func)) {
564  return NULL;
565  }
566 
567  if (!iter->c->v_table || !iter->c->v_table->iterator_next) {
568  /* Sanity checks. */
569  __ast_assert_failed(0, "invalid iterator container v_table", file, line, func);
570  return NULL;
571  }
572 
573  if (iter->complete) {
574  /* Don't return any more objects. */
575  return NULL;
576  }
577 
578  if (iter->flags & AO2_ITERATOR_DONTLOCK) {
579  if (iter->flags & AO2_ITERATOR_UNLINK) {
580  orig_lock = __adjust_lock(iter->c, AO2_LOCK_REQ_WRLOCK, 1);
581  } else {
582  orig_lock = __adjust_lock(iter->c, AO2_LOCK_REQ_RDLOCK, 1);
583  }
584  } else {
585  orig_lock = AO2_LOCK_REQ_MUTEX;
586  if (iter->flags & AO2_ITERATOR_UNLINK) {
587  ao2_wrlock(iter->c);
588  } else {
589  ao2_rdlock(iter->c);
590  }
591  }
592 
593  node = iter->c->v_table->iterator_next(iter->c, iter->last_node, iter->flags);
594  if (node) {
595  ret = node->obj;
596 
597  if (iter->flags & AO2_ITERATOR_UNLINK) {
598  /* Transfer the object ref from the container to the returned object. */
600 
601  /* Transfer the container's node ref to the iterator. */
602  } else {
603  /* Bump ref of returned object */
604  __ao2_ref(ret, +1, tag ?: "Next iterator object.", file, line, func);
605 
606  /* Bump the container's node ref for the iterator. */
607  ao2_ref(node, +1);
608  }
609  } else {
610  /* The iteration has completed. */
611  iter->complete = 1;
612  ret = NULL;
613  }
614 
615  /* Replace the iterator's node */
616  if (iter->last_node) {
617  ao2_ref(iter->last_node, -1);
618  }
619  iter->last_node = node;
620 
621  if (iter->flags & AO2_ITERATOR_DONTLOCK) {
622  __adjust_lock(iter->c, orig_lock, 0);
623  } else {
624  ao2_unlock(iter->c);
625  }
626 
627  return ret;
628 }
enum ao2_lock_req __adjust_lock(void *user_data, enum ao2_lock_req lock_how, int keep_stronger)
Definition: astobj2.c:425
#define ao2_rdlock(a)
Definition: astobj2.h:718
ao2_lock_req
Which lock to request.
Definition: astobj2.h:700
int __container_unlink_node_debug(struct ao2_container_node *node, uint32_t flags, const char *tag, const char *file, int line, const char *func)
@ AO2_UNLINK_NODE_DEC_COUNT
ao2_iterator_next_fn iterator_next
Generic container node.
int complete
Definition: astobj2.h:1827
struct ao2_container * c
Definition: astobj2.h:1823
void * last_node
Definition: astobj2.h:1825
Definition: test_heap.c:38

References __adjust_lock(), __ao2_ref(), __ast_assert_failed(), __container_unlink_node_debug(), __is_ao2_object, AO2_ITERATOR_DONTLOCK, AO2_ITERATOR_UNLINK, AO2_LOCK_REQ_MUTEX, AO2_LOCK_REQ_RDLOCK, AO2_LOCK_REQ_WRLOCK, ao2_rdlock, ao2_ref, AO2_UNLINK_NODE_DEC_COUNT, ao2_unlock, ao2_wrlock, ao2_iterator::c, ao2_iterator::complete, make_ari_stubs::file, ao2_iterator::flags, ao2_container_methods::iterator_next, ao2_iterator::last_node, NULL, and ao2_container::v_table.

◆ __ao2_link()

int __ao2_link ( struct ao2_container c,
void *  obj_new,
int  flags,
const char *  tag,
const char *  file,
int  line,
const char *  func 
)

Definition at line 94 of file astobj2_container.c.

96 {
97  int res;
98  enum ao2_lock_req orig_lock;
99  struct ao2_container_node *node;
100 
101  if (!__is_ao2_object(obj_new, file, line, func)
102  || !__is_ao2_object(self, file, line, func)) {
103  return 0;
104  }
105 
106  if (!self->v_table || !self->v_table->new_node || !self->v_table->insert) {
107  /* Sanity checks. */
108  __ast_assert_failed(0, "invalid container v_table", file, line, func);
109  return 0;
110  }
111 
112  if (flags & OBJ_NOLOCK) {
113  orig_lock = __adjust_lock(self, AO2_LOCK_REQ_WRLOCK, 1);
114  } else {
115  ao2_wrlock(self);
116  orig_lock = AO2_LOCK_REQ_MUTEX;
117  }
118 
119  res = 0;
120  node = self->v_table->new_node(self, obj_new, tag, file, line, func);
121  if (node) {
122 #if defined(AO2_DEBUG)
123  if (ao2_container_check(self, OBJ_NOLOCK)) {
124  ast_log(LOG_ERROR, "Container integrity failed before insert.\n");
125  }
126 #endif /* defined(AO2_DEBUG) */
127 
128  /* Insert the new node. */
129  switch (self->v_table->insert(self, node)) {
131  node->is_linked = 1;
132  ast_atomic_fetchadd_int(&self->elements, 1);
133 #if defined(AO2_DEBUG)
134  AO2_DEVMODE_STAT(++self->nodes);
135  if (self->v_table->link_stat) {
136  self->v_table->link_stat(self, node);
137  }
138 #endif /* defined(AO2_DEBUG) */
139  /* Fall through */
141 #if defined(AO2_DEBUG)
142  if (ao2_container_check(self, OBJ_NOLOCK)) {
143  ast_log(LOG_ERROR, "Container integrity failed after insert or replace.\n");
144  }
145 #endif /* defined(AO2_DEBUG) */
146  res = 1;
147  break;
149  ao2_ref(node, -1);
150  break;
151  }
152  }
153 
154  if (flags & OBJ_NOLOCK) {
155  __adjust_lock(self, orig_lock, 0);
156  } else {
157  ao2_unlock(self);
158  }
159 
160  return res;
161 }
int ao2_container_check(struct ao2_container *self, enum search_flags flags)
Perform an integrity check on the specified container.
@ AO2_CONTAINER_INSERT_NODE_OBJ_REPLACED
@ AO2_CONTAINER_INSERT_NODE_REJECTED
@ AO2_CONTAINER_INSERT_NODE_INSERTED
#define AO2_DEVMODE_STAT(stat)
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:755

References __adjust_lock(), __ast_assert_failed(), __is_ao2_object, ao2_container_check(), AO2_CONTAINER_INSERT_NODE_INSERTED, AO2_CONTAINER_INSERT_NODE_OBJ_REPLACED, AO2_CONTAINER_INSERT_NODE_REJECTED, AO2_DEVMODE_STAT, AO2_LOCK_REQ_MUTEX, AO2_LOCK_REQ_WRLOCK, ao2_ref, ao2_unlock, ao2_wrlock, ast_atomic_fetchadd_int(), ast_log, make_ari_stubs::file, LOG_ERROR, and OBJ_NOLOCK.

Referenced by internal_ao2_traverse().

◆ __ao2_lock()

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.

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;
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 }
#define var
Definition: ast_expr2f.c:614
#define INTERNAL_OBJ_LOCKOBJ(user_data)
Definition: astobj2.c:160
static FILE * ref_log
Definition: astobj2.c:44
#define INTERNAL_OBJ_MUTEX(user_data)
Definition: astobj2.c:154
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_RWLOCK(user_data)
Definition: astobj2.c:157
int __ast_pthread_mutex_lock(const char *filename, int lineno, const char *func, const char *mutex_name, ast_mutex_t *t)
Definition: lock.c:253
uint32_t options
The ao2 object option flags.
Definition: astobj2.c:70
uint32_t lockused
Set to 1 when the lock is used if refdebug is enabled.
Definition: astobj2.c:77
ast_mutex_t lock
Definition: astobj2.c:116
ast_rwlock_t lock
Definition: astobj2.c:127
struct ao2_lock_priv mutex
Definition: astobj2.c:121
struct ao2_lockobj_priv lockobj
Definition: astobj2.c:145
void * user_data[0]
Definition: astobj2.c:147
struct ao2_rwlock_priv rwlock
Definition: astobj2.c:134
void * user_data[0]
Definition: astobj2.c:106

References __ao2_lock(), __ast_pthread_mutex_lock(), __ast_rwlock_rdlock(), __ast_rwlock_wrlock(), __INTERNAL_OBJ_CHECK, __LOG_ERROR, AO2_ALLOC_OPT_LOCK_MASK, AO2_ALLOC_OPT_LOCK_MUTEX, AO2_ALLOC_OPT_LOCK_NOLOCK, AO2_ALLOC_OPT_LOCK_OBJ, AO2_ALLOC_OPT_LOCK_RWLOCK, AO2_LOCK_REQ_MUTEX, AO2_LOCK_REQ_RDLOCK, AO2_LOCK_REQ_WRLOCK, ast_atomic_fetchadd_int(), ast_log, make_ari_stubs::file, INTERNAL_OBJ_LOCKOBJ, INTERNAL_OBJ_MUTEX, INTERNAL_OBJ_RWLOCK, ao2_lock_priv::lock, ao2_rwlock_priv::lock, ao2_lockobj_priv::lock, astobj2_lockobj::lockobj, __priv_data::lockused, astobj2_lock::mutex, NULL, ao2_rwlock_priv::num_lockers, __priv_data::options, astobj2::priv_data, ref_log, astobj2_rwlock::rwlock, astobj2::user_data, astobj2_lockobj::user_data, and var.

Referenced by __ao2_lock(), _agent_lock(), _ast_bridge_channel_lock(), and _ast_bridge_lock().

◆ __ao2_ref()

int __ao2_ref ( void *  o,
int  delta,
const char *  tag,
const char *  file,
int  line,
const char *  func 
)

Definition at line 498 of file astobj2.c.

500 {
501  struct astobj2 *obj = __INTERNAL_OBJ_CHECK(user_data, file, line, func);
502  struct astobj2_lock *obj_mutex;
503  struct astobj2_rwlock *obj_rwlock;
504  struct astobj2_lockobj *obj_lockobj;
505  int32_t current_value;
506  int32_t ret;
507  uint32_t privdataoptions;
508  struct ao2_weakproxy *weakproxy = NULL;
509  const char *lock_state;
510 
511  if (obj == NULL) {
512  if (ref_log && user_data) {
513  fprintf(ref_log, "%p,%d,%d,%s,%d,%s,**invalid**,%s\n",
514  user_data, delta, ast_get_tid(), file, line, func, tag ?: "");
515  fflush(ref_log);
516  }
517  return -1;
518  }
519 
520  /* if delta is 0, just return the refcount */
521  if (delta == 0) {
522  return obj->priv_data.ref_counter;
523  }
524 
525  if (delta < 0 && obj->priv_data.magic == AO2_MAGIC && (weakproxy = obj->priv_data.weakptr)) {
526  ao2_lock(weakproxy);
527  }
528 
529  /* we modify with an atomic operation the reference counter */
530  ret = ast_atomic_fetch_add(&obj->priv_data.ref_counter, delta, __ATOMIC_RELAXED);
531  current_value = ret + delta;
532 
533 #ifdef AO2_DEBUG
534  ast_atomic_fetchadd_int(&ao2.total_refs, delta);
535 #endif
536 
537  if (weakproxy) {
538  struct ao2_weakproxy cbs;
539 
540  if (current_value == 1) {
541  /* The only remaining reference is the one owned by the weak object */
542  struct astobj2 *internal_weakproxy;
543 
544  internal_weakproxy = INTERNAL_OBJ_CHECK(weakproxy);
545 
546  /* Unlink the obj from the weak proxy */
547  internal_weakproxy->priv_data.weakptr = NULL;
548  obj->priv_data.weakptr = NULL;
549 
550  /* transfer list to local copy so callbacks are run with weakproxy unlocked. */
551  cbs.destroyed_cb = weakproxy->destroyed_cb;
553 
554  /* weak is already unlinked from obj so this won't recurse */
555  ao2_ref(user_data, -1);
556  }
557 
558  ao2_unlock(weakproxy);
559 
560  if (current_value == 1) {
561  struct ao2_weakproxy_notification *destroyed_cb;
562 
563  /* Notify the subscribers that weakproxy now points to NULL. */
564  while ((destroyed_cb = AST_LIST_REMOVE_HEAD(&cbs.destroyed_cb, list))) {
565  destroyed_cb->cb(weakproxy, destroyed_cb->data);
566  ast_free(destroyed_cb);
567  }
568 
569  ao2_ref(weakproxy, -1);
570  }
571  }
572 
573  if (0 < current_value) {
574  /* The object still lives. */
575 #define EXCESSIVE_REF_COUNT 100000
576 
577  if (EXCESSIVE_REF_COUNT <= current_value && ret < EXCESSIVE_REF_COUNT) {
578  char excessive_ref_buf[100];
579 
580  /* We just reached or went over the excessive ref count trigger */
581  snprintf(excessive_ref_buf, sizeof(excessive_ref_buf),
582  "Excessive refcount %d reached on ao2 object %p",
583  (int)current_value, user_data);
584  ast_log(__LOG_ERROR, file, line, func, "%s\n", excessive_ref_buf);
585 
586  __ast_assert_failed(0, excessive_ref_buf, file, line, func);
587  }
588 
590  fprintf(ref_log, "%p,%s%d,%d,%s,%d,%s,%d,%s\n", user_data,
591  (delta < 0 ? "" : "+"), delta, ast_get_tid(),
592  file, line, func, (int)ret, tag ?: "");
593  fflush(ref_log);
594  }
595  return ret;
596  }
597 
598  /* this case must never happen */
599  if (current_value < 0) {
600  ast_log(__LOG_ERROR, file, line, func,
601  "Invalid refcount %d on ao2 object %p\n", (int)current_value, user_data);
602  if (ref_log) {
603  /* Log to ref_log even if AO2_ALLOC_OPT_NO_REF_DEBUG */
604  fprintf(ref_log, "%p,%d,%d,%s,%d,%s,**invalid**,%s\n",
605  user_data, delta, ast_get_tid(), file, line, func, tag ?: "");
606  fflush(ref_log);
607  }
608  ast_assert(0);
609  /* stop here even if assert doesn't DO_CRASH */
610  return -1;
611  }
612 
613  /* last reference, destroy the object */
614  if (obj->priv_data.destructor_fn != NULL) {
615  obj->priv_data.destructor_fn(user_data);
616  }
617 
618 #ifdef AO2_DEBUG
619  ast_atomic_fetchadd_int(&ao2.total_mem, - obj->priv_data.data_size);
620  ast_atomic_fetchadd_int(&ao2.total_objects, -1);
621 #endif
622 
623  /* In case someone uses an object after it's been freed */
624  obj->priv_data.magic = 0;
625  /* Save the options locally so the ref_log print at the end doesn't access freed data */
626  privdataoptions = obj->priv_data.options;
627 
628  switch (obj->priv_data.options & AO2_ALLOC_OPT_LOCK_MASK) {
630  obj_mutex = INTERNAL_OBJ_MUTEX(user_data);
631  lock_state = obj->priv_data.lockused ? "used" : "unused";
632  ast_mutex_destroy(&obj_mutex->mutex.lock);
633 
634  ast_free(obj_mutex);
635  break;
637  obj_rwlock = INTERNAL_OBJ_RWLOCK(user_data);
638  lock_state = obj->priv_data.lockused ? "used" : "unused";
639  ast_rwlock_destroy(&obj_rwlock->rwlock.lock);
640 
641  ast_free(obj_rwlock);
642  break;
644  lock_state = "none";
645  ast_free(obj);
646  break;
648  obj_lockobj = INTERNAL_OBJ_LOCKOBJ(user_data);
649  lock_state = obj->priv_data.lockused ? "used" : "unused";
650  ao2_t_ref(obj_lockobj->lockobj.lock, -1, "release lockobj");
651 
652  ast_free(obj_lockobj);
653  break;
654  default:
655  ast_log(__LOG_ERROR, file, line, func,
656  "Invalid lock option on ao2 object %p\n", user_data);
657  lock_state = "invalid";
658  break;
659  }
660 
661  if (ref_log && !(privdataoptions & AO2_ALLOC_OPT_NO_REF_DEBUG)) {
662  fprintf(ref_log, "%p,%d,%d,%s,%d,%s,**destructor**lock-state:%s**,%s\n",
663  user_data, delta, ast_get_tid(), file, line, func, lock_state, tag ?: "");
664  fflush(ref_log);
665  }
666 
667  return ret;
668 }
#define ast_free(a)
Definition: astmm.h:180
#define EXCESSIVE_REF_COUNT
#define INTERNAL_OBJ_CHECK(user_data)
Definition: astobj2.c:183
#define ao2_t_ref(o, delta, tag)
Definition: astobj2.h:460
#define ao2_lock(a)
Definition: astobj2.h:717
int int32_t
Definition: db.h:60
#define AST_LIST_HEAD_INIT_NOLOCK(head)
Initializes a list head structure.
Definition: linkedlists.h:681
#define AST_LIST_REMOVE_HEAD(head, field)
Removes and returns the head entry from a list.
Definition: linkedlists.h:833
#define ast_rwlock_destroy(rwlock)
Definition: lock.h:231
#define ast_mutex_destroy(a)
Definition: lock.h:186
#define ast_atomic_fetch_add(ptr, val, memorder)
Support for atomic instructions.
Definition: lock.h:667
int32_t ref_counter
Definition: astobj2.c:63
ao2_destructor_fn destructor_fn
Definition: astobj2.c:55
struct ao2_weakproxy_notification::@328 list
ao2_weakproxy_notification_cb cb
Definition: astobj2.c:110
This struct should be opaque, but it's size is needed.
Definition: astobj2.h:529
struct ao2_weakproxy::@213 destroyed_cb
int ast_get_tid(void)
Get current thread ID.
Definition: main/utils.c:2650

References __ast_assert_failed(), __INTERNAL_OBJ_CHECK, __LOG_ERROR, AO2_ALLOC_OPT_LOCK_MASK, AO2_ALLOC_OPT_LOCK_MUTEX, AO2_ALLOC_OPT_LOCK_NOLOCK, AO2_ALLOC_OPT_LOCK_OBJ, AO2_ALLOC_OPT_LOCK_RWLOCK, AO2_ALLOC_OPT_NO_REF_DEBUG, ao2_lock, AO2_MAGIC, ao2_ref, ao2_t_ref, ao2_unlock, ast_assert, ast_atomic_fetch_add, ast_atomic_fetchadd_int(), ast_free, ast_get_tid(), AST_LIST_HEAD_INIT_NOLOCK, AST_LIST_REMOVE_HEAD, ast_log, ast_mutex_destroy, ast_rwlock_destroy, ao2_weakproxy_notification::cb, ao2_weakproxy_notification::data, ao2_weakproxy::destroyed_cb, __priv_data::destructor_fn, EXCESSIVE_REF_COUNT, make_ari_stubs::file, INTERNAL_OBJ_CHECK, INTERNAL_OBJ_LOCKOBJ, INTERNAL_OBJ_MUTEX, INTERNAL_OBJ_RWLOCK, ao2_weakproxy_notification::list, ao2_lock_priv::lock, ao2_rwlock_priv::lock, ao2_lockobj_priv::lock, astobj2_lockobj::lockobj, __priv_data::lockused, __priv_data::magic, astobj2_lock::mutex, NULL, __priv_data::options, astobj2::priv_data, __priv_data::ref_counter, ref_log, astobj2_rwlock::rwlock, astobj2::user_data, and __priv_data::weakptr.

Referenced by __ao2_cleanup_debug(), __ao2_container_clone(), __ao2_get_weakproxy(), __ao2_global_obj_ref(), __ao2_global_obj_replace(), __ao2_global_obj_replace_unref(), __ao2_iterator_next(), __ao2_weakproxy_get_object(), __ao2_weakproxy_ref_object(), __ao2_weakproxy_set_object(), __ast_format_cap_append(), __ast_module_ref(), __ast_module_unref(), __container_unlink_node_debug(), __find_call(), hash_ao2_insert_node(), internal_ao2_traverse(), and rb_ao2_new_node().

◆ __ao2_trylock()

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.

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;
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
int __ast_rwlock_trywrlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name)
Definition: lock.c:1228
int __ast_pthread_mutex_trylock(const char *filename, int lineno, const char *func, const char *mutex_name, ast_mutex_t *t)
Definition: lock.c:366
int __ast_rwlock_tryrdlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name)
Definition: lock.c:1178

Referenced by __adjust_lock(), _ast_bridge_channel_trylock(), and _ast_bridge_trylock().

◆ __ao2_unlink()

void* __ao2_unlink ( struct ao2_container c,
void *  obj,
int  flags,
const char *  tag,
const char *  file,
int  line,
const char *  func 
)

Definition at line 175 of file astobj2_container.c.

177 {
178  if (!__is_ao2_object(user_data, file, line, func)) {
179  /* Sanity checks. */
180  return NULL;
181  }
182 
183  flags &= ~OBJ_SEARCH_MASK;
184  flags |= (OBJ_UNLINK | OBJ_SEARCH_OBJECT | OBJ_NODATA);
185  __ao2_callback(c, flags, ao2_match_by_addr, user_data, tag, file, line, func);
186 
187  return NULL;
188 }
int ao2_match_by_addr(void *user_data, void *arg, int flags)
another convenience function is a callback that matches on address

References __ao2_callback(), __is_ao2_object, ao2_match_by_addr(), c, make_ari_stubs::file, NULL, OBJ_NODATA, OBJ_SEARCH_MASK, OBJ_SEARCH_OBJECT, and OBJ_UNLINK.

◆ __ao2_unlock()

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.

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;
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 }
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_pthread_mutex_unlock(const char *filename, int lineno, const char *func, const char *mutex_name, ast_mutex_t *t)
Definition: lock.c:421

References __ao2_unlock(), __ast_pthread_mutex_unlock(), __ast_rwlock_unlock(), __INTERNAL_OBJ_CHECK, __LOG_ERROR, AO2_ALLOC_OPT_LOCK_MASK, AO2_ALLOC_OPT_LOCK_MUTEX, AO2_ALLOC_OPT_LOCK_NOLOCK, AO2_ALLOC_OPT_LOCK_OBJ, AO2_ALLOC_OPT_LOCK_RWLOCK, ast_atomic_fetchadd_int(), ast_log, make_ari_stubs::file, INTERNAL_OBJ_LOCKOBJ, INTERNAL_OBJ_MUTEX, INTERNAL_OBJ_RWLOCK, ao2_lock_priv::lock, ao2_rwlock_priv::lock, ao2_lockobj_priv::lock, astobj2_lockobj::lockobj, astobj2_lock::mutex, NULL, ao2_rwlock_priv::num_lockers, __priv_data::options, astobj2::priv_data, astobj2_rwlock::rwlock, astobj2::user_data, astobj2_lockobj::user_data, and var.

Referenced by __ao2_unlock(), _agent_unlock(), _ast_bridge_channel_unlock(), and _ast_bridge_unlock().

◆ __ao2_weakproxy_alloc()

void* __ao2_weakproxy_alloc ( size_t  data_size,
ao2_destructor_fn  destructor_fn,
const char *  tag,
const char *  file,
int  line,
const char *  func 
)

Definition at line 793 of file astobj2.c.

795 {
796  struct ao2_weakproxy *weakproxy;
797 
798  if (data_size < sizeof(*weakproxy)) {
799  ast_assert(0);
800  ast_log(LOG_ERROR, "Requested data_size smaller than minimum.\n");
801  return NULL;
802  }
803 
804  weakproxy = __ao2_alloc(data_size, destructor_fn, AO2_ALLOC_OPT_LOCK_MUTEX,
805  tag, file, line, func);
806 
807  if (weakproxy) {
808  struct astobj2 *weakproxy_internal;
809 
810  /* Just created weakproxy, no need to check if it's valid. */
811  weakproxy_internal = INTERNAL_OBJ(weakproxy);
812  weakproxy_internal->priv_data.magic = AO2_WEAK;
813  }
814 
815  return weakproxy;
816 }
#define AO2_WEAK
Definition: astobj2.c:97
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)
Definition: astobj2.c:768
#define INTERNAL_OBJ(user_data)
Definition: astobj2.c:163

References __ao2_alloc(), AO2_ALLOC_OPT_LOCK_MUTEX, AO2_WEAK, ast_assert, ast_log, make_ari_stubs::file, INTERNAL_OBJ, LOG_ERROR, __priv_data::magic, NULL, and astobj2::priv_data.

◆ __ao2_weakproxy_find()

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 
)

Definition at line 440 of file astobj2_container.c.

442 {
443  void *proxy;
444  void *obj = NULL;
445  enum ao2_lock_req orig_lock;
446 
447  ast_assert(!!c);
448  ast_assert(flags & OBJ_SEARCH_MASK);
449  ast_assert(!(flags & ~(OBJ_SEARCH_MASK | OBJ_NOLOCK)));
450 
451  if (flags & OBJ_NOLOCK) {
452  orig_lock = __adjust_lock(c, AO2_LOCK_REQ_RDLOCK, 1);
453  } else {
454  orig_lock = AO2_LOCK_REQ_RDLOCK;
455  ao2_rdlock(c);
456  }
457 
458  while ((proxy = ao2_find(c, arg, flags | OBJ_NOLOCK))) {
459  obj = __ao2_weakproxy_get_object(proxy, 0, tag ?: __PRETTY_FUNCTION__, file, line, func);
460 
461  if (obj) {
462  ao2_ref(proxy, -1);
463  break;
464  }
465 
466  /* Upgrade to a write lock */
468  ao2_unlink_flags(c, proxy, OBJ_NOLOCK);
469  ao2_ref(proxy, -1);
470  }
471 
472  if (flags & OBJ_NOLOCK) {
473  /* We'll keep any upgraded lock */
474  __adjust_lock(c, orig_lock, 1);
475  } else {
476  ao2_unlock(c);
477  }
478 
479  return obj;
480 }
void * __ao2_weakproxy_get_object(void *weakproxy, int flags, const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result
Definition: astobj2.c:889
#define ao2_unlink_flags(container, obj, flags)
Remove an object from a container.
Definition: astobj2.h:1600
#define ao2_find(container, arg, flags)
Definition: astobj2.h:1736

References __adjust_lock(), __ao2_weakproxy_get_object(), ao2_find, AO2_LOCK_REQ_RDLOCK, AO2_LOCK_REQ_WRLOCK, ao2_rdlock, ao2_ref, ao2_unlink_flags, ao2_unlock, ast_assert, c, make_ari_stubs::file, ao2_iterator::flags, NULL, OBJ_NOLOCK, and OBJ_SEARCH_MASK.

Referenced by __ast_named_lock_get(), and __ast_sorcery_open().

◆ __ao2_weakproxy_get_object()

void* __ao2_weakproxy_get_object ( void *  weakproxy,
int  flags,
const char *  tag,
const char *  file,
int  line,
const char *  func 
)

Definition at line 889 of file astobj2.c.

891 {
892  struct astobj2 *internal = __INTERNAL_OBJ_CHECK(weakproxy, file, line, func);
893  void *obj;
894 
895  if (!internal || internal->priv_data.magic != AO2_WEAK) {
896  /* This method is meant to be run on weakproxy objects! */
897  return NULL;
898  }
899 
900  /* We have a weak object, grab reference to object within lock */
901  if (!(flags & OBJ_NOLOCK)) {
902  ao2_lock(weakproxy);
903  }
904 
905  obj = internal->priv_data.weakptr;
906  if (obj) {
907  __ao2_ref(obj, +1, tag, file, line, func);
908  }
909 
910  if (!(flags & OBJ_NOLOCK)) {
911  ao2_unlock(weakproxy);
912  }
913 
914  return obj;
915 }

References __ao2_ref(), __INTERNAL_OBJ_CHECK, ao2_lock, ao2_unlock, AO2_WEAK, make_ari_stubs::file, NULL, and OBJ_NOLOCK.

Referenced by __ao2_weakproxy_find().

◆ __ao2_weakproxy_ref_object()

int __ao2_weakproxy_ref_object ( void *  weakproxy,
int  delta,
int  flags,
const char *  tag,
const char *  file,
int  line,
const char *  func 
)

Definition at line 862 of file astobj2.c.

864 {
865  struct astobj2 *internal = __INTERNAL_OBJ_CHECK(weakproxy, file, line, func);
866  int ret = -1;
867 
868  if (!internal || internal->priv_data.magic != AO2_WEAK) {
869  /* This method is meant to be run on weakproxy objects! */
870  return -2;
871  }
872 
873  /* We have a weak object, grab lock. */
874  if (!(flags & OBJ_NOLOCK)) {
875  ao2_lock(weakproxy);
876  }
877 
878  if (internal->priv_data.weakptr) {
879  ret = __ao2_ref(internal->priv_data.weakptr, delta, tag, file, line, func);
880  }
881 
882  if (!(flags & OBJ_NOLOCK)) {
883  ao2_unlock(weakproxy);
884  }
885 
886  return ret;
887 }

References __ao2_ref(), __INTERNAL_OBJ_CHECK, ao2_lock, ao2_unlock, AO2_WEAK, make_ari_stubs::file, and OBJ_NOLOCK.

◆ __ao2_weakproxy_set_object()

int __ao2_weakproxy_set_object ( void *  weakproxy,
void *  obj,
int  flags,
const char *  tag,
const char *  file,
int  line,
const char *  func 
)

Definition at line 818 of file astobj2.c.

820 {
821  struct astobj2 *weakproxy_internal = __INTERNAL_OBJ_CHECK(weakproxy, file, line, func);
822  struct astobj2 *obj_internal = __INTERNAL_OBJ_CHECK(obj, file, line, func);
823  int ret = -1;
824 
825  if (!weakproxy_internal
826  || weakproxy_internal->priv_data.magic != AO2_WEAK) {
827  return -1;
828  }
829 
830  if (!obj_internal
831  || obj_internal->priv_data.weakptr
832  || obj_internal->priv_data.magic != AO2_MAGIC) {
833  return -1;
834  }
835 
836  if (!(flags & OBJ_NOLOCK)) {
837  ao2_lock(weakproxy);
838  }
839 
840  if (!weakproxy_internal->priv_data.weakptr) {
841  __ao2_ref(obj, +1, tag, file, line, func);
842  __ao2_ref(weakproxy, +1, tag, file, line, func);
843 
844  weakproxy_internal->priv_data.weakptr = obj;
845  obj_internal->priv_data.weakptr = weakproxy;
846 
847  ret = 0;
848  }
849 
850  if (!(flags & OBJ_NOLOCK)) {
851  ao2_unlock(weakproxy);
852  /* It is possible for obj to be accessed now. It's allowed
853  * for weakproxy to already be in a container. Another thread
854  * could have been waiting for a lock on weakproxy to retrieve
855  * the object.
856  */
857  }
858 
859  return ret;
860 }

References __ao2_ref(), __INTERNAL_OBJ_CHECK, ao2_lock, AO2_MAGIC, ao2_unlock, AO2_WEAK, make_ari_stubs::file, __priv_data::magic, OBJ_NOLOCK, astobj2::priv_data, and __priv_data::weakptr.

◆ ao2_container_check()

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 }
#define is_ao2_object(user_data)

References ao2_rdlock, ao2_unlock, ast_assert, is_ao2_object, and OBJ_NOLOCK.

Referenced by __ao2_link(), AST_TEST_DEFINE(), astobj2_test_1_helper(), hash_ao2_node_destructor(), insert_test_duplicates(), insert_test_vector(), rb_ao2_node_destructor(), and test_container_clone().

◆ ao2_container_count()

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.

35 {
36  return ast_atomic_fetchadd_int(&c->elements, 0);
37 }

References ast_atomic_fetchadd_int(), and c.

Referenced by _sip_show_peers(), action_confbridgekick(), action_confbridgelist(), action_confbridgelistrooms(), action_confbridgesetsinglevideosrc(), action_confbridgestartrecord(), action_confbridgestoprecord(), action_lock_unlock_helper(), action_mute_unmute_helper(), ami_show_aors(), ami_show_auths(), ami_show_contacts(), ami_show_endpoints(), ami_show_resource_lists(), ao2_iterator_count(), app_is_finished(), ari_show(), ast_active_channels(), ast_ari_applications_list(), ast_cdr_generic_unregister(), ast_endpoint_snapshot_create(), ast_get_chan_applicationmap(), ast_get_namedgroups(), ast_namedgroups_intersect(), ast_sip_cli_traverse_objects(), ast_sip_initialize_system(), ast_sip_location_retrieve_first_aor_contact_filtered(), 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_srtp_unprotect(), AST_TEST_DEFINE(), ast_tone_zone_count(), astobj2_test_1_helper(), auth_observer(), calc_metric(), cc_cli_output_status(), cel_pre_apply_config(), check_events(), check_expiration_thread(), cleanup(), cleanup_module(), cli_display_parking_lot(), cli_fax_show_sessions(), cli_show_modules(), common_identify(), control_command_count(), control_wait(), cpg_confchg_cb(), create_sound_blob(), create_unsolicited_mwi_subscriptions(), device_state_cb(), do_timing(), endelm(), exten_state_pub_data_alloc(), format_ami_aor_handler(), get_device_state_causing_channels(), global_loaded_observer(), grow(), handle_manager_show_events(), handle_registrations(), handle_show_hint(), handle_show_hints(), insert_test_vector(), ip_identify_apply(), load_common(), match_filter(), member_add_to_queue(), memory_cache_full_update(), memory_cache_populate(), mid_test_sync(), mwi_subscription_established(), native_bridge_is_capable(), native_rtp_bridge_compatible_check(), object_type_loaded_observer(), one_protocol(), parking_lot_remove_if_unused(), pjsip_acf_dial_contacts_read(), print_queue(), process_config(), pthread_timer_open(), publisher_start(), queue_exec(), queue_function_mem_read(), queued_set_size(), queued_task_pushed(), send_unsolicited_mwi_notify(), shrink(), sip_options_apply_aor_configuration(), sip_options_contact_add_task(), sip_options_contact_delete_task(), sip_options_unused_endpoint_state_compositor(), sip_send_all_registers(), sip_show_objects(), sla_in_use(), smdi_load(), sorcery_memory_cache_create(), sorcery_memory_cache_dump(), sorcery_memory_cache_retrieve_multiple(), sorcery_memory_cache_retrieve_prefix(), sorcery_memory_cache_retrieve_regex(), sorcery_memory_cache_show(), sorcery_object_load(), stale_cache_update(), stasis_app_set_global_debug(), stasis_app_to_cli(), stir_shaken_general_get(), system_create_resolver_and_set_nameservers(), test_ao2_iteration(), test_cel_peer_strings_match(), test_container_clone(), test_sub(), threadpool_send_state_changed(), try_calling(), unload_module(), and xmpp_show_clients().

◆ ao2_container_dump()

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.

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 }

References ao2_rdlock, ao2_unlock, ast_assert, is_ao2_object, name, and OBJ_NOLOCK.

Referenced by astobj2_test_1_helper(), and test_traversal_sorted().

◆ ao2_container_dup()

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.

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. */
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,...
Definition: astobj2.h:1693
static int dup_obj_cb(void *obj, void *arg, int flags)

References ao2_callback, ao2_rdlock, ao2_t_ref, ao2_unlock, ao2_wrlock, dup_obj_cb(), NULL, OBJ_MULTIPLE, OBJ_NODATA, OBJ_NOLOCK, and OBJ_UNLINK.

Referenced by __ao2_container_clone(), __queues_show(), cli_aor_get_container(), cli_endpoint_get_container(), cli_get_container(), cli_unid_get_container(), handle_cli_sounds_show(), sip_options_apply_aor_configuration(), stasis_show_topics(), and tps_report_taskprocessor_list().

◆ ao2_container_dup_weakproxy_objs()

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.

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. */
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 }
static int dup_weakproxy_cb(void *proxy, void *arg, int flags)
Copy obj associated with a weakproxy into the arg container.

References ao2_callback, ao2_rdlock, ao2_t_ref, ao2_unlock, ao2_wrlock, dup_weakproxy_cb(), NULL, OBJ_MULTIPLE, OBJ_NODATA, OBJ_NOLOCK, and OBJ_UNLINK.

Referenced by AST_TEST_DEFINE().

◆ ao2_container_register()

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.

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_link(container, obj, tag)
Definition: astobj2.h:1534
#define ao2_t_alloc_options(data_size, destructor_fn, options, debug_msg)
Allocate and initialize an object.
Definition: astobj2.h:402

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_t_alloc_options, ao2_t_link, ao2_t_ref, and name.

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

◆ ao2_container_stats()

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.

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 }

References ao2_rdlock, ao2_unlock, ast_assert, is_ao2_object, name, and OBJ_NOLOCK.

Referenced by astobj2_test_1_helper(), and test_traversal_sorted().

◆ ao2_container_unregister()

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.

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 }
#define ao2_t_find(container, arg, flags, tag)
Definition: astobj2.h:1734

References ao2_t_find, name, OBJ_NODATA, OBJ_SEARCH_KEY, and OBJ_UNLINK.

Referenced by bridge_cleanup(), cdr_engine_shutdown(), channels_shutdown(), load_module(), stasis_caching_topic_dtor(), state_manager_dtor(), topic_pool_dtor(), and unload_module().

◆ ao2_iterator_cleanup()

void ao2_iterator_cleanup ( struct ao2_iterator iter)

Definition at line 549 of file astobj2_container.c.

550 {
551  if (iter) {
552  ao2_iterator_destroy(iter);
553  }
554 }
void ao2_iterator_destroy(struct ao2_iterator *iter)
Destroy a container iterator.

References ao2_iterator_destroy().

Referenced by AST_TEST_DEFINE(), and stasis_app_set_global_debug().

◆ ao2_iterator_count()

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.

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.

References ao2_container_count(), and ao2_iterator::c.

◆ ao2_iterator_destroy()

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.

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.

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

Referenced by __find_call(), __iax2_show_peers(), __manager_event_sessions_va(), __queues_show(), __test_cel_generate_peer_str(), _sip_show_peers(), aco_set_defaults(), action_agents(), action_confbridgelistrooms(), action_coreshowchannels(), action_devicestatelist(), action_meetmelist(), action_presencestatelist(), add_ice_to_sdp(), add_ice_to_stream(), aeap_tab_complete_name(), agent_show_requested(), agents_post_apply_config(), agents_sweep(), alias_show(), ami_show_registration_contact_statuses(), ao2_iterator_cleanup(), app_to_json(), ari_show_apps(), 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_cel_str_to_event_type(), ast_channel_iterator_destroy(), ast_complete_channels(), ast_endpoint_snapshot_create(), ast_format_cache_get_by_codec(), ast_msg_var_iterator_destroy(), ast_multi_channel_blob_get_channels(), ast_pickup_find_by_group(), ast_print_namedgroups(), ast_sip_destroy_scheduler(), ast_sip_for_each_contact(), ast_sorcery_objectset_create2(), ast_sorcery_objectset_json_create(), ast_srtp_unprotect(), AST_TEST_DEFINE(), ast_var_indications(), ast_var_indications_table(), astman_verify_session_readpermissions(), astman_verify_session_writepermissions(), astobj2_test_1_helper(), attended_transfer_bridge(), auth_observer(), authenticate(), authenticate_reply(), bridge_app_subscribed_involved(), bridge_channel_event_join_leave(), bridge_channel_moving(), bridge_channel_talking(), build_cli_notify(), calendar_query_exec(), cel_generate_peer_str(), check_access(), check_events(), clear_queue(), clear_stats(), cli_complete_endpoint(), cli_complete_notify(), cli_complete_registration(), cli_complete_show(), cli_complete_uri(), cli_display_named_acl_list(), cli_fax_show_sessions(), cli_list_devices(), cli_show_channels(), cli_show_modules(), cli_tps_reset_stats_all(), compare_weight(), complete_bridge_profile_name(), complete_confbridge_name(), complete_config_module(), complete_core_id(), complete_core_show_hint(), complete_country(), complete_iax2_peers(), complete_iax2_unregister(), complete_menu_name(), complete_mohclass_realtime(), complete_queue(), complete_show_sorcery_object(), complete_sip_peer(), complete_sip_registered_peer(), complete_sip_user(), complete_sipch(), complete_user_profile_name(), complete_userno(), conf_queue_dtmf(), config_hook_exec(), configure_parking_extensions(), container_to_json_array(), control_dispatch_all(), control_flush_queue(), control_prestart_dispatch_all(), destroy_pvts(), device_state_cb(), device_state_notify_callbacks(), dialgroup_read(), disable_marked_lots(), dump_queue_members(), event_session_shutdown(), exten_state_publisher_state_cb(), extension_state_cb(), fax_session_tab_complete(), find_queue_by_name_rt(), find_ringing_channel(), find_session(), find_session_by_nonce(), free_members(), generate_or_link_lots_to_configs(), get_device_state_causing_channels(), get_member_status(), get_udp_transport(), get_write_timeout(), handle_bridge_pairings(), handle_bridge_show_all(), handle_chanlist(), handle_cli_confbridge_list(), handle_cli_confbridge_show_bridge_profiles(), handle_cli_confbridge_show_menus(), handle_cli_confbridge_show_user_profiles(), handle_cli_iax2_show_callno_limits(), handle_cli_iax2_show_users(), handle_cli_indication_show(), handle_cli_moh_show_files(), handle_cli_moh_unregister_class(), handle_manager_show_events(), handle_show_calendar(), handle_show_calendars(), handle_show_hint(), handle_show_hints(), handle_showmanconn(), handle_skel_show_games(), handle_skel_show_levels(), handle_voicemail_show_aliases(), has_mwi_subscription(), iax2_getpeername(), iax2_getpeertrunk(), interface_exists(), ip_identify_apply(), jingle_add_google_candidates_to_transport(), jingle_add_ice_udp_candidates_to_transport(), jingle_request(), keepalive_transport_thread(), kill_duplicate_offers(), load_users(), local_devicestate(), manager_iax2_show_peer_list(), manager_parking_status_all_lots(), manager_parking_status_single_lot(), manager_queues_status(), manager_queues_summary(), manager_show_registry(), manager_sip_peer_status(), mark_lots_as_disabled(), media_cache_handle_show_item(), meetme_menu_admin_extended(), meetme_show_cmd(), moh_rescan_files(), msg_func_write(), mwi_contact_deleted(), mwi_initial_events(), mwi_mailbox_delete_all(), mwi_mailbox_get(), mwi_subscription_mailboxes_str(), num_available_members(), parking_lot_get_space(), pjsip_acf_dial_contacts_read(), poke_all_peers(), pp_each_user_helper(), presence_state_notify_callbacks(), print_queue(), prune_peers(), prune_users(), purge_sessions(), queue_function_mem_read(), queue_function_qac_dep(), queue_function_queuememberlist(), queue_mwi_event(), reload(), reload_single_queue(), remove_all_configured_parking_lot_extensions(), remove_pending_parking_lot_extensions(), rt_handle_member_record(), set_member_paused(), set_member_value(), set_transfer_variables_all(), show_codecs(), sip_keepalive_all_peers(), sip_options_apply_aor_configuration(), sip_options_cleanup_task(), sip_options_endpoint_unlink_aor_feeders(), sip_outbound_publish_synchronize(), sip_poke_all_peers(), sip_prune_realtime(), sip_send_all_mwi_subscriptions(), sip_send_all_registers(), sip_show_channel(), sip_show_channels(), sip_show_channelstats(), sip_show_history(), sip_show_inuse(), sip_show_mwi(), sip_show_objects(), sip_show_registry(), sip_show_tcp(), sip_show_users(), sla_calc_station_delays(), sla_change_trunk_state(), sla_queue_event_conf(), sla_show_trunks(), sorcery_memory_cache_complete_name(), sorcery_memory_cache_complete_object_name(), stasis_app_mailboxes_to_json(), stasis_app_to_cli(), stasis_show_topics(), stir_shaken_tab_complete_name(), stop_streams(), system_create_resolver_and_set_nameservers(), test_ao2_callback_traversal(), test_ao2_iteration(), test_container_clone(), test_expected_duplicates(), topic_complete_name(), tps_report_taskprocessor_list(), tps_taskprocessor_tab_complete(), try_calling(), unbound_config_preapply(), unlink_peers_from_tables(), update_queue(), update_realtime_members(), xmpp_pubsub_create_affiliations(), and xmpp_show_clients().

◆ ao2_iterator_init()

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 440 of file astobj2_container.c.

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 }
When we need to walk through a container, we use an ao2_iterator to keep track of the current positio...
Definition: astobj2.h:1821
static struct test_val a

Referenced by __iax2_show_peers(), __manager_event_sessions_va(), __queues_show(), __test_cel_generate_peer_str(), aco_set_defaults(), action_agents(), action_confbridgelistrooms(), action_coreshowchannels(), action_devicestatelist(), action_meetmelist(), action_presencestatelist(), add_ice_to_sdp(), add_ice_to_stream(), aeap_tab_complete_name(), agent_show_requested(), agents_post_apply_config(), alias_show(), ami_show_registration_contact_statuses(), app_to_json(), ari_show_apps(), 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_cel_str_to_event_type(), ast_channel_iterator_all_new(), ast_complete_channels(), ast_endpoint_snapshot_create(), ast_format_cache_get_by_codec(), ast_msg_var_iterator_init(), ast_pickup_find_by_group(), ast_print_namedgroups(), ast_sip_destroy_scheduler(), ast_sip_for_each_contact(), ast_sorcery_objectset_create2(), ast_sorcery_objectset_json_create(), ast_srtp_unprotect(), AST_TEST_DEFINE(), astman_verify_session_readpermissions(), astman_verify_session_writepermissions(), astobj2_test_1_helper(), attended_transfer_bridge(), auth_observer(), authenticate(), authenticate_reply(), bridge_app_subscribed_involved(), bridge_channel_event_join_leave(), bridge_channel_moving(), bridge_channel_talking(), build_cli_notify(), calendar_query_exec(), cel_generate_peer_str(), check_access(), check_events(), clear_queue(), clear_stats(), cli_complete_endpoint(), cli_complete_notify(), cli_complete_registration(), cli_complete_show(), cli_complete_uri(), cli_display_named_acl_list(), cli_fax_show_sessions(), cli_list_devices(), cli_show_channels(), cli_show_modules(), cli_tps_reset_stats_all(), compare_weight(), complete_bridge_profile_name(), complete_confbridge_name(), complete_config_module(), complete_core_id(), complete_core_show_hint(), complete_country(), complete_iax2_peers(), complete_iax2_unregister(), complete_menu_name(), complete_mohclass_realtime(), complete_queue(), complete_show_sorcery_object(), complete_sip_peer(), complete_sip_registered_peer(), complete_sip_user(), complete_sipch(), complete_user_profile_name(), complete_userno(), conf_queue_dtmf(), config_hook_exec(), configure_parking_extensions(), container_to_json_array(), control_dispatch_all(), control_flush_queue(), control_prestart_dispatch_all(), destroy_pvts(), device_state_cb(), device_state_notify_callbacks(), dialgroup_read(), disable_marked_lots(), dump_queue_members(), event_session_shutdown(), exten_state_publisher_state_cb(), extension_state_cb(), fax_session_tab_complete(), find_queue_by_name_rt(), find_ringing_channel(), find_session(), find_session_by_nonce(), free_members(), generate_or_link_lots_to_configs(), get_device_state_causing_channels(), get_member_status(), get_udp_transport(), get_write_timeout(), handle_bridge_pairings(), handle_bridge_show_all(), handle_chanlist(), handle_cli_confbridge_list(), handle_cli_confbridge_show_bridge_profiles(), handle_cli_confbridge_show_menus(), handle_cli_confbridge_show_user_profiles(), handle_cli_iax2_show_callno_limits(), handle_cli_iax2_show_users(), handle_cli_moh_show_files(), handle_cli_moh_unregister_class(), handle_show_calendar(), handle_show_calendars(), handle_show_hint(), handle_show_hints(), handle_showmanconn(), handle_skel_show_games(), handle_skel_show_levels(), handle_voicemail_show_aliases(), iax2_getpeername(), iax2_getpeertrunk(), interface_exists(), internal_ao2_traverse(), ip_identify_apply(), jingle_add_google_candidates_to_transport(), jingle_add_ice_udp_candidates_to_transport(), jingle_request(), keepalive_transport_thread(), load_users(), local_devicestate(), manager_iax2_show_peer_list(), manager_parking_status_all_lots(), manager_parking_status_single_lot(), manager_queues_status(), manager_queues_summary(), manager_show_registry(), manager_sip_peer_status(), mark_lots_as_disabled(), media_cache_handle_show_item(), meetme_menu_admin_extended(), meetme_show_cmd(), moh_rescan_files(), msg_func_write(), mwi_initial_events(), mwi_mailbox_delete_all(), mwi_mailbox_get(), mwi_subscription_mailboxes_str(), num_available_members(), parking_lot_get_space(), pjsip_acf_dial_contacts_read(), poke_all_peers(), pp_each_user_helper(), presence_state_notify_callbacks(), print_queue(), prune_peers(), prune_users(), purge_sessions(), queue_function_mem_read(), queue_function_qac_dep(), queue_function_queuememberlist(), reload(), reload_single_queue(), remove_all_configured_parking_lot_extensions(), remove_pending_parking_lot_extensions(), rt_handle_member_record(), set_member_paused(), set_member_value(), set_transfer_variables_all(), show_codecs(), sip_keepalive_all_peers(), sip_options_apply_aor_configuration(), sip_options_cleanup_task(), sip_options_endpoint_unlink_aor_feeders(), sip_outbound_publish_synchronize(), sip_poke_all_peers(), sip_prune_realtime(), sip_send_all_mwi_subscriptions(), sip_send_all_registers(), sip_show_channel(), sip_show_channels(), sip_show_channelstats(), sip_show_history(), sip_show_inuse(), sip_show_mwi(), sip_show_objects(), sip_show_registry(), sip_show_tcp(), sip_show_users(), sla_calc_station_delays(), sla_change_trunk_state(), sla_queue_event_conf(), sla_show_trunks(), sorcery_memory_cache_complete_name(), sorcery_memory_cache_complete_object_name(), stasis_app_mailboxes_to_json(), stasis_app_set_global_debug(), stasis_show_topics(), stir_shaken_tab_complete_name(), stop_streams(), system_create_resolver_and_set_nameservers(), test_ao2_iteration(), test_container_clone(), topic_complete_name(), tps_report_taskprocessor_list(), tps_taskprocessor_tab_complete(), try_calling(), unbound_config_preapply(), update_queue(), update_realtime_members(), xmpp_pubsub_create_affiliations(), and xmpp_show_clients().

◆ ao2_iterator_restart()

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.

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 }

References __adjust_lock(), AO2_ITERATOR_DONTLOCK, AO2_LOCK_REQ_MUTEX, AO2_LOCK_REQ_RDLOCK, ao2_rdlock, ao2_ref, ao2_unlock, ao2_iterator::c, ao2_iterator::complete, ao2_iterator::flags, is_ao2_object, ao2_iterator::last_node, and NULL.

Referenced by ao2_iterator_destroy().

◆ ao2_match_by_addr()

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.

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

References CMP_MATCH, and CMP_STOP.

Referenced by __ao2_unlink(), and test_container_clone().

◆ ao2_object_get_lockaddr()

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.

477 {
478  struct astobj2 *obj;
479  struct astobj2_lock *obj_mutex;
480 
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 }
void * user_data[0]
Definition: astobj2.c:123

References AO2_ALLOC_OPT_LOCK_MASK, AO2_ALLOC_OPT_LOCK_MUTEX, INTERNAL_OBJ_CHECK, INTERNAL_OBJ_MUTEX, ao2_lock_priv::lock, astobj2_lock::mutex, NULL, __priv_data::options, astobj2::priv_data, and astobj2_lock::user_data.

Referenced by ast_serializer_shutdown_group_join(), ast_sip_session_suspend(), bridge_channel_wait(), bridge_manager_thread(), consumer_should_stay(), consumer_wait_for(), consumer_wait_for_completion(), control_wait(), db_sync_thread(), rtp_deallocate_transport(), sip_session_suspend_task(), and stasis_subscription_join().

◆ ao2_options_get()

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.

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 }

References INTERNAL_OBJ_CHECK, __priv_data::options, and astobj2::priv_data.

Referenced by __ast_named_lock_get(), hash_ao2_alloc_empty_clone(), and rb_ao2_alloc_empty_clone().

◆ ao2_ref_and_lock()

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.

792 {

References ao2_ref, and ao2_unlock.

◆ ao2_unlock_and_unref()

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 {

◆ ao2_weakproxy_subscribe()

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.

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;
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 }
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
#define AST_LIST_INSERT_HEAD(head, elm, field)
Inserts a list entry at the head of a list.
Definition: linkedlists.h:711
struct stasis_forward * sub
Definition: res_corosync.c:240

References ao2_lock, ao2_unlock, AO2_WEAK, ast_calloc, AST_LIST_INSERT_HEAD, ao2_weakproxy_notification::cb, ao2_weakproxy_notification::data, ao2_weakproxy::destroyed_cb, INTERNAL_OBJ_CHECK, ao2_weakproxy_notification::list, __priv_data::magic, NULL, OBJ_NOLOCK, astobj2::priv_data, sub, and __priv_data::weakptr.

Referenced by __ast_named_lock_get(), __ast_sorcery_open(), AST_TEST_DEFINE(), link_topic_proxy(), and state_alloc().

◆ ao2_weakproxy_unsubscribe()

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.

974 {
975  struct astobj2 *internal_weakproxy = INTERNAL_OBJ_CHECK(weakproxy);
976  struct ao2_weakproxy *weak;
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;
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 }
#define AST_LIST_TRAVERSE_SAFE_END
Closes a safe loop traversal block.
Definition: linkedlists.h:615
#define AST_LIST_TRAVERSE_SAFE_BEGIN(head, var, field)
Loops safely over (traverses) the entries in a list.
Definition: linkedlists.h:529
#define AST_LIST_REMOVE_CURRENT(field)
Removes the current entry from a list during a traversal.
Definition: linkedlists.h:557

References ao2_lock, ao2_unlock, AO2_WEAK, ast_free, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, ao2_weakproxy_notification::data, ao2_weakproxy::destroyed_cb, INTERNAL_OBJ_CHECK, ao2_weakproxy_notification::list, __priv_data::magic, OBJ_MULTIPLE, OBJ_NOLOCK, astobj2::priv_data, and sub.

Referenced by AST_TEST_DEFINE().