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.
#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.
#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.
#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.
#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.
#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.
#define	AO2_GLOBAL_OBJ_STATIC(name)
	Define a global object holder to be used to hold an ao2 object, statically initialized.
#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.
#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.
#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.
#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.
#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.
#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.
typedef int()	ao2_callback_fn(void *obj, void *arg, int flags)
	Type of a generic callback function.
typedef void(*	ao2_destructor_fn) (void *vdoomed)
	Typedef for an object destructor.
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.

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.
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)
int	__ao2_unlock (void *a, const char *file, const char *func, int line, const char *var)
	Unlock an object.
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.
void	ao2_iterator_destroy (struct ao2_iterator *iter)
	Destroy a container iterator.
struct ao2_iterator	ao2_iterator_init (struct ao2_container *c, int flags) attribute_warn_unused_result
	Create an iterator for a container.
void	ao2_iterator_restart (struct ao2_iterator *iter)
	Restart an iteration.
int	ao2_match_by_addr (void *obj, void *arg, int flags)
	A common ao2_callback is one that matches by address.
void *	ao2_object_get_lockaddr (void *obj)
	Return the mutex lock address of an object.
int	ao2_ref_and_lock (void *obj)
	Increment reference count on an object and lock it.
int	ao2_unlock_and_unref (void *obj)
	Unlock an object and decrement its reference count.
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.
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.
unsigned int	ao2_options_get (void *obj)
	Retrieve the ao2 options used to create the object.
#define	ao2_ref(o, delta)   __ao2_ref((o), (delta), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
	Reference/unreference an object and return the old refcount.
#define	ao2_replace(dst, src)    ao2_t_replace((dst), (src), NULL)
	Replace one object reference with another cleaning up the original.
#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.
#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.
#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.
#define	ao2_weakproxy_get_object(weakproxy, flags)    __ao2_weakproxy_get_object(weakproxy, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
	Get the object associated with weakproxy.
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.
#define	ao2_weakproxy_set_object(weakproxy, obj, flags)    __ao2_weakproxy_set_object(weakproxy, obj, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
	Associate weakproxy with obj.
int	ao2_weakproxy_subscribe (void *weakproxy, ao2_weakproxy_notification_cb cb, void *data, int flags)
	Request notification when weakproxy points to NULL.
int	ao2_weakproxy_unsubscribe (void *weakproxy, ao2_weakproxy_notification_cb cb, void *data, int flags)
	Remove notification of real object destruction.

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.
#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.
#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.
int	ao2_container_check (struct ao2_container *self, enum search_flags flags)
	Perform an integrity check on the specified container.
#define	ao2_container_clone(orig, flags)    __ao2_container_clone(orig, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
	Create a clone/copy of the given container.
int	ao2_container_count (struct ao2_container *c)
	Returns the number of elements in a container.
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.
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.
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.
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.
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.
void	ao2_container_unregister (const char *name)
	Unregister a container for CLI stats and integrity check.
typedef void()	ao2_prnt_fn(void *where, const char *fmt,...)
	Print output.
typedef void()	ao2_prnt_obj_fn(void *v_obj, void *where, ao2_prnt_fn *prnt)
	Print object key.
#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.
#define	ao2_link_flags(container, obj, flags)    __ao2_link((container), (obj), (flags), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
	Add an object to a container.
#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.
#define	ao2_unlink_flags(container, obj, flags)    __ao2_unlink((container), (obj), (flags), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
	Remove an object from a container.
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.
#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.

     {                          \
        typeof(obj) __obj_ ## __LINE__ = (obj);     \
        if (__obj_ ## __LINE__) {           \
            ao2_t_ref(__obj_ ## __LINE__, +1, (tag));   \
        }                       \
        __obj_ ## __LINE__;             \
    })
 
int __ao2_ref(void *o, int delta, const char *tag, const char *file, int line, const char *func);
 
/*!
 * \since 12.4.0
 * \brief Replace one object reference with another cleaning up the original.
 *
 * \param dst Pointer to the object that will be cleaned up.
 * \param src Pointer to the object replacing it.
 */
#define ao2_replace(dst, src) \
    ao2_t_replace((dst), (src), NULL)
 
#define ao2_t_replace(dst, src, tag) \
    {\
        typeof(dst) *__dst_ ## __LINE__ = &dst; \
        typeof(src) __src_ ## __LINE__ = src; \
        if (__src_ ## __LINE__ != *__dst_ ## __LINE__) { \
            if (__src_ ## __LINE__) {\
                ao2_t_ref(__src_ ## __LINE__, +1, (tag)); \
            } \
            if (*__dst_ ## __LINE__) {\
                ao2_t_ref(*__dst_ ## __LINE__, -1, (tag)); \
            } \
            *__dst_ ## __LINE__ = __src_ ## __LINE__; \
        } \
    }
 
/*! @} */
 
/*! \brief ao2_weakproxy
 *
 * @{
 */
struct ao2_weakproxy_notification;
typedef void (*ao2_weakproxy_notification_cb)(void *weakproxy, void *data);
 
/*! \brief This struct should be opaque, but it's size is needed. */
struct ao2_weakproxy {
    AST_LIST_HEAD_NOLOCK(, ao2_weakproxy_notification) destroyed_cb;
};
 
/*! \brief 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.
 */
#define AO2_WEAKPROXY() struct ao2_weakproxy __weakproxy##__LINE__
 
/*!
 * \since 14.0.0
 * \brief Allocate an ao2_weakproxy object
 *
 * \param data_size The sizeof() of the user-defined structure.
 * \param destructor_fn The 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.
 */
#define ao2_weakproxy_alloc(data_size, destructor_fn) \
    __ao2_weakproxy_alloc(data_size, destructor_fn, NULL, __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__)
 
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;
 
/*!
 * \since 14.0.0
 * \brief Associate weakproxy with obj.
 *
 * \param weakproxy An object created by ao2_weakproxy_alloc.
 * \param obj An ao2 object not created by ao2_weakproxy_alloc.
 * \param flags OBJ_NOLOCK to avoid locking weakproxy.
 *
 * \retval 0 Success
 * \retval -1 Failure
 *
 * \note obj must be newly created, this procedure is not thread safe
 *       if any other code can reach obj before this procedure ends.
 *
 * \note weakproxy may be previously existing, but must not currently
 *       have an object set.
 *
 * \note 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.
 */
#define ao2_weakproxy_set_object(weakproxy, obj, flags) \
    __ao2_weakproxy_set_object(weakproxy, obj, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_t_weakproxy_set_object(weakproxy, obj, flags, tag) \
    __ao2_weakproxy_set_object(weakproxy, obj, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
int __ao2_weakproxy_set_object(void *weakproxy, void *obj, int flags,
    const char *tag, const char *file, int line, const char *func);
 
/*!
 * \since 14.0.0
 * \brief Run ao2_t_ref on the object associated with weakproxy.
 *
 * \param weakproxy The weakproxy to read from.
 * \param delta Value to add to the reference counter.
 * \param flags OBJ_NOLOCK to avoid locking weakproxy.
 *
 * \retval -2 weakproxy is not a valid ao2_weakproxy.
 * \retval -1 weakproxy has no associated object.
 *
 * \return The value of the reference counter before the operation.
 */
#define ao2_weakproxy_ref_object(weakproxy, delta, flags) \
    ao2_t_weakproxy_ref_object(weakproxy, delta, flags, NULL)
 
#define ao2_t_weakproxy_ref_object(weakproxy, delta, flags, tag) \
    __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);
 
/*!
 * \since 14.0.0
 * \brief Get the object associated with weakproxy.
 *
 * \param weakproxy The weakproxy to read from.
 * \param flags OBJ_NOLOCK to avoid locking weakproxy.
 *
 * \return A reference to the object previously set by ao2_weakproxy_set_object.
 * \retval NULL Either no object was set or the previously set object has been freed.
 */
#define ao2_weakproxy_get_object(weakproxy, flags) \
    __ao2_weakproxy_get_object(weakproxy, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_t_weakproxy_get_object(weakproxy, flags, tag) \
    __ao2_weakproxy_get_object(weakproxy, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
void *__ao2_weakproxy_get_object(void *weakproxy, int flags,
    const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result;
 
/*!
 * \since 14.0.0
 * \brief Request notification when weakproxy points to NULL.
 *
 * \param weakproxy The weak object
 * \param cb Procedure to call when no real object is associated
 * \param data Passed to cb
 * \param flags OBJ_NOLOCK to avoid locking weakproxy.
 *
 * \retval 0 Success
 * \retval -1 Failure
 *
 * \note Callbacks are run in the reverse order of subscriptions.
 *
 * \note This procedure will allow the same cb / data pair to be added to
 *       the same weakproxy multiple times.
 *
 * \note It is the caller's responsibility to ensure that *data is valid
 *       until after cb() is run or ao2_weakproxy_unsubscribe is called.
 *
 * \note If the weakproxy currently points to NULL the callback will be run immediately,
 *       without being added to the subscriber list.
 */
int ao2_weakproxy_subscribe(void *weakproxy, ao2_weakproxy_notification_cb cb, void *data, int flags);
 
/*!
 * \since 14.0.0
 * \brief Remove notification of real object destruction.
 *
 * \param weakproxy The weak object
 * \param cb Callback to remove from destroy notification list
 * \param data Data pointer to match
 * \param flags OBJ_NOLOCK to avoid locking weakproxy.
 *              OBJ_MULTIPLE to remove all copies of the same cb / data pair.
 *
 * \return The number of subscriptions removed.
 * \retval 0 cb / data pair not found, nothing removed.
 * \retval -1 Failure 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.
 *
 * \note 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.
 */
int ao2_weakproxy_unsubscribe(void *weakproxy, ao2_weakproxy_notification_cb cb, void *data, int flags);
 
/*!
 * \since 14.0.0
 * \brief Get the weakproxy attached to obj
 *
 * \param obj The object to retrieve a weakproxy from
 *
 * \return The weakproxy object
 */
#define ao2_get_weakproxy(obj) \
    __ao2_get_weakproxy(obj, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_t_get_weakproxy(obj, tag) \
    __ao2_get_weakproxy(obj, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
void *__ao2_get_weakproxy(void *obj,
    const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result;
/*! @} */
 
 
/*! \brief Which lock to request. */
enum ao2_lock_req {
    /*! Request the mutex lock be acquired. */
    AO2_LOCK_REQ_MUTEX,
    /*! Request the read lock be acquired. */
    AO2_LOCK_REQ_RDLOCK,
    /*! Request the write lock be acquired. */
    AO2_LOCK_REQ_WRLOCK,
};
 
/*! \brief
 * Lock an object.
 *
 * \param a A pointer to the object we want to lock.
 * \param lock_how, file, func, line, var
 * \return 0 on success, other values on error.
 */
int __ao2_lock(void *a, enum ao2_lock_req lock_how, const char *file, const char *func, int line, const char *var);
#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_wrlock(a) __ao2_lock(a, AO2_LOCK_REQ_WRLOCK, __FILE__, __PRETTY_FUNCTION__, __LINE__, #a)
 
/*! \brief
 * Unlock an object.
 *
 * \param a A pointer to the object we want unlock.
 * \param file, func, line, var
 * \return 0 on success, other values on error.
 */
int __ao2_unlock(void *a, const char *file, const char *func, int line, const char *var);
#define ao2_unlock(a) __ao2_unlock(a, __FILE__, __PRETTY_FUNCTION__, __LINE__, #a)
 
/*! \brief
 * Try locking-- (don't block if fail)
 *
 * \param a A pointer to the object we want to lock.
 * \param lock_how, file, func, line, var
 * \return 0 on success, other values on error.
 */
int __ao2_trylock(void *a, enum ao2_lock_req lock_how, const char *file, const char *func, int line, const char *var);
#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)
 
/*!
 * \brief Return the mutex lock address of an object
 *
 * \param[in] obj A pointer to the object we want.
 * \return 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
 */
void *ao2_object_get_lockaddr(void *obj);
 
 
/*!
 * \brief Increment reference count on an object and lock it
 * \since 13.9.0
 *
 * \param[in] obj A pointer to the ao2 object
 * \retval 0 The object is not an ao2 object or wasn't locked successfully
 * \retval 1 The object's reference count was incremented and was locked
 */
AST_INLINE_API(
int ao2_ref_and_lock(void *obj),
{
    ao2_ref(obj, +1);
    if (ao2_lock(obj)) {
        ao2_ref(obj, -1);
        return 0;
    }
    return 1;
}
)
 
/*!
 * \brief Unlock an object and decrement its reference count
 * \since 13.9.0
 *
 * \param[in] obj A pointer to the ao2 object
 * \retval 0 The object is not an ao2 object or wasn't unlocked successfully
 * \retval 1 The object was unlocked and it's reference count was decremented
 */
AST_INLINE_API(
int ao2_unlock_and_unref(void *obj),
{
    if (ao2_unlock(obj)) {
        return 0;
    }
    ao2_ref(obj, -1);
 
    return 1;
}
)
 
/*! Global ao2 object holder structure. */
struct ao2_global_obj {
    /*! Access lock to the held ao2 object. */
    ast_rwlock_t lock;
    /*! Global ao2 object. */
    void *obj;
};
 
/*!
 * \brief Define a global object holder to be used to hold an ao2 object, statically initialized.
 * \since 11.0
 *
 * \param name This will be the name of the object holder.
 *
 * \details
 * 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:
 * \code
 * static AO2_GLOBAL_OBJ_STATIC(global_cfg);
 * \endcode
 *
 * This defines global_cfg, intended to hold an ao2 object
 * accessible using an API.
 */
#ifndef HAVE_PTHREAD_RWLOCK_INITIALIZER
#define AO2_GLOBAL_OBJ_STATIC(name)                                     \
    struct ao2_global_obj name;                                         \
    static void  __attribute__((constructor)) __init_##name(void)       \
    {                                                                   \
        ast_rwlock_init(&name.lock);                                    \
        name.obj = NULL;                                                \
    }                                                                   \
    static void  __attribute__((destructor)) __fini_##name(void)        \
    {                                                                   \
        if (name.obj) {                                                 \
            ao2_ref(name.obj, -1);                                      \
            name.obj = NULL;                                            \
        }                                                               \
        ast_rwlock_destroy(&name.lock);                                 \
    }                                                                   \
    struct __dummy_##name
#else
#define AO2_GLOBAL_OBJ_STATIC(name)                                     \
    struct ao2_global_obj name = {                                      \
        .lock = AST_RWLOCK_INIT_VALUE,                                  \
    }
#endif
 
/*!
 * \brief Release the ao2 object held in the global holder.
 * \since 11.0
 *
 * \param holder Global ao2 object holder.
 */
#define ao2_global_obj_release(holder)  \
    __ao2_global_obj_replace_unref(&holder, NULL, NULL, __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)
 
/*!
 * \brief Replace an ao2 object in the global holder.
 * \since 11.0
 *
 * \param holder Global ao2 object holder.
 * \param obj Object 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.
 *
 * \return Reference to previous global ao2 object stored.
 * \retval NULL if no object available.
 */
#define ao2_global_obj_replace(holder, obj) \
    __ao2_global_obj_replace(&holder, (obj), NULL, __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)
 
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;
 
/*!
 * \brief Replace an ao2 object in the global holder, throwing away any old object.
 * \since 11.0
 *
 * \param holder Global ao2 object holder.
 * \param obj Object 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.
 *
 * \retval 0 The global object was previously empty
 * \retval 1 The global object was not previously empty
 */
#define ao2_global_obj_replace_unref(holder, obj)   \
    __ao2_global_obj_replace_unref(&holder, (obj), NULL, __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)
 
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);
 
/*!
 * \brief Get a reference to the object stored in the global holder.
 * \since 11.0
 *
 * \param holder Global ao2 object holder.
 *
 * \return Reference to current ao2 object stored in the holder.
 * \retval NULL if no object available.
 */
#define ao2_global_obj_ref(holder)  \
    __ao2_global_obj_ref(&holder, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
 
#define ao2_t_global_obj_ref(holder, tag)   \
    __ao2_global_obj_ref(&holder, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
 
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;
 
 
/*!
 \page AstObj2_Containers AstObj2 Containers
 
Containers are data structures meant to store several objects,
and perform various operations on them.
Internally, objects are stored in lists, hash tables or other
data structures depending on the needs.
 
Operations on container include:
 
  -  \b ao2_find(c, arg, flags)
    returns zero or more elements matching a given criteria
    (specified as arg). 'c' is the container pointer. Flags
    can be:
    OBJ_UNLINK - to remove the object, once found, from the container.
    OBJ_NODATA - don't return the object if found (no ref count change)
    OBJ_MULTIPLE - don't stop at first match
    OBJ_SEARCH_OBJECT - if set, 'arg' is an object pointer, and a hash table
                  search will be done. If not, a traversal is done.
    OBJ_SEARCH_KEY - if set, 'arg', is a search key item that is not an object.
              Similar to OBJ_SEARCH_OBJECT and mutually exclusive.
    OBJ_SEARCH_PARTIAL_KEY - if set, 'arg', is a partial search key item that is not an object.
              Similar to OBJ_SEARCH_KEY and mutually exclusive.
 
  -  \b ao2_callback(c, flags, fn, arg)
    apply fn(obj, arg) to all objects in the container.
    Similar to find. fn() can tell when to stop, and
    do anything with the object including unlinking it.
      - c is the container;
      - flags can be
         OBJ_UNLINK   - to remove the object, once found, from the container.
         OBJ_NODATA   - don't return the object if found (no ref count change)
         OBJ_MULTIPLE - don't stop at first match
         OBJ_SEARCH_OBJECT - if set, 'arg' is an object pointer, and a hash table
                        search will be done. If not, a traversal is done through
                        all the hash table 'buckets'..
         OBJ_SEARCH_KEY - if set, 'arg', is a search key item that is not an object.
                        Similar to OBJ_SEARCH_OBJECT and mutually exclusive.
         OBJ_SEARCH_PARTIAL_KEY - if set, 'arg', is a partial search key item that is not an object.
                        Similar to OBJ_SEARCH_KEY and mutually exclusive.
      - fn is a func that returns int, and takes 3 args:
        (void *obj, void *arg, int flags);
          obj is an object
          arg is the same as arg passed into ao2_callback
          flags is the same as flags passed into ao2_callback
         fn returns:
           0: no match, keep going
           CMP_STOP: stop search, no match
           CMP_MATCH: This object is matched.
 
    Note that the entire operation is run with the container
    locked, so nobody else can change its content while we work on it.
    However, we pay this with the fact that doing
    anything blocking in the callback keeps the container
    blocked.
    The mechanism is very flexible because the callback function fn()
    can do basically anything e.g. counting, deleting records, etc.
    possibly using arg to store the results.
 
  -  \b iterate on a container
    this is done with the following sequence
 
\code
 
        struct ao2_container *c = ... // our container
        struct ao2_iterator i;
        void *o;
 
        i = ao2_iterator_init(c, flags);
 
        while ((o = ao2_iterator_next(&i))) {
            ... do something on o ...
            ao2_ref(o, -1);
        }
 
        ao2_iterator_destroy(&i);
\endcode
 
    The difference with the callback is that the control
    on how to iterate is left to us.
 
    - \b ao2_ref(c, -1)
    dropping a reference to a container destroys it, very simple!
 
Containers are ao2 objects themselves, and this is why their
implementation is simple too.
 
Before declaring containers, we need to declare the types of the
arguments passed to the constructor - in turn, this requires
to define callback and hash functions and their arguments.
 
- \ref AstObj2
- \ref astobj2.h
 */
 
/*! \brief
 * A callback function will return a combination of CMP_MATCH and CMP_STOP.
 * The latter will terminate the search in a container.
 */
enum _cb_results {
    CMP_MATCH   = 0x1,  /*!< the object matches the request */
    CMP_STOP    = 0x2,  /*!< stop the search now */
};
 
/*!
 * \brief Flags passed to ao2_callback_fn(), ao2_hash_fn(), and ao2_sort_fn() to modify behaviour.
 */
enum search_flags {
    /*!
     * Unlink the object for which the callback function returned
     * CMP_MATCH.
     */
    OBJ_UNLINK = (1 << 0),
    /*!
     * On match, don't return the object hence do not increase its
     * refcount.
     */
    OBJ_NODATA = (1 << 1),
    /*!
     * Don't stop at the first match in ao2_callback() unless the
     * result of the callback function has the CMP_STOP bit set.
     */
    OBJ_MULTIPLE = (1 << 2),
    /*!
     * \brief Assume that the ao2_container is already locked.
     *
     * \note For ao2_containers that have mutexes, no locking will
     * be done.
     *
     * \note 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.
     *
     * \note Only use this flag if the ao2_container is manually
     * locked already.
     */
    OBJ_NOLOCK = (1 << 4),
 
    /*!
     * \brief 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_MASK = (0x07 << 5),
    /*! \brief The arg parameter has no meaning to the astobj2 code. */
    OBJ_SEARCH_NONE = (0 << 5),
    /*!
     * \brief The arg parameter is an object of the same type.
     *
     * \details
     * 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_OBJECT = (1 << 5),
    /*!
     * \brief The arg parameter is a search key, but is not an object.
     *
     * \details
     * 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_KEY = (2 << 5),
    /*!
     * \brief The arg parameter is a partial search key similar to OBJ_SEARCH_KEY.
     *
     * \details
     * 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_SEARCH_PARTIAL_KEY = (4 << 5),
 
    /*! \brief Traverse order option field mask. */
    OBJ_ORDER_MASK = (0x03 << 8),
    /*! \brief Traverse in ascending order (First to last container object) */
    OBJ_ORDER_ASCENDING = (0 << 8),
    /*! \brief Traverse in descending order (Last to first container object) */
    OBJ_ORDER_DESCENDING = (1 << 8),
    /*!
     * \brief 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_PRE = (2 << 8),
    /*!
     * \brief 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.
     */
    OBJ_ORDER_POST = (3 << 8),
};
 
/*
 * Deprecated backward compatible flag names.
 *
 * Note: OBJ_POINTER, OBJ_KEY, and OBJ_PARTIAL_KEY are mutually
 * exclusive.
 */
#define OBJ_POINTER     OBJ_SEARCH_OBJECT       /*!< Deprecated name */
#define OBJ_KEY         OBJ_SEARCH_KEY          /*!< Deprecated name */
#define OBJ_PARTIAL_KEY OBJ_SEARCH_PARTIAL_KEY  /*!< Deprecated name */
 
/*!
 * \brief 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.
 */
enum ao2_container_opts {
    /*!
     * \brief 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.
     *
     * \note Hash containers insert the object in the computed hash
     * bucket in the indicated manner.
     */
    AO2_CONTAINER_ALLOC_OPT_INSERT_BEGIN = (1 << 0),
 
    /*!
     * \brief The ao2 container objects with duplicate keys option field mask.
     */
    AO2_CONTAINER_ALLOC_OPT_DUPS_MASK = (3 << 1),
    /*!
     * \brief Allow objects with duplicate keys in container.
     */
    AO2_CONTAINER_ALLOC_OPT_DUPS_ALLOW = (0 << 1),
    /*!
     * \brief 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_REJECT = (1 << 1),
    /*!
     * \brief Reject duplicate objects in container.
     *
     * \details 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.
     *
     * \note It is assumed that the objects are located where the
     * search key says they should be located.
     */
    AO2_CONTAINER_ALLOC_OPT_DUPS_OBJ_REJECT = (2 << 1),
    /*!
     * \brief Replace objects with duplicate keys in container.
     *
     * \details 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.
     */
    AO2_CONTAINER_ALLOC_OPT_DUPS_REPLACE = (3 << 1),
};
 
/*!
 * \brief Type of a generic callback function
 * \param obj  pointer to the (user-defined part) of an object.
 * \param arg callback argument from ao2_callback()
 * \param flags flags 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.
 */
typedef int (ao2_callback_fn)(void *obj, void *arg, int flags);
 
/*! \brief A common ao2_callback is one that matches by address. */
int ao2_match_by_addr(void *obj, void *arg, int flags);
 
/*!
 * \brief Type of a generic callback function
 * \param obj pointer to the (user-defined part) of an object.
 * \param arg callback argument from ao2_callback()
 * \param data arbitrary data from ao2_callback()
 * \param flags flags 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.
 */
typedef int (ao2_callback_data_fn)(void *obj, void *arg, void *data, int flags);
 
/*!
 * Type of a generic function to generate a hash value from an object.
 *
 * \param obj pointer to the (user-defined part) of an object.
 * \param flags flags 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.
 *
 * \return Computed hash value.
 */
typedef int (ao2_hash_fn)(const void *obj, int flags);
 
/*!
 * \brief Type of generic container sort function.
 *
 * \param obj_left pointer to the (user-defined part) of an object.
 * \param obj_right pointer to the (user-defined part) of an object.
 * \param flags flags 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.
 *
 * \retval negtaive if obj_left < obj_right
 * \retval 0 if obj_left == obj_right
 * \retval positive if obj_left > obj_right
 */
typedef int (ao2_sort_fn)(const void *obj_left, const void *obj_right, int flags);
 
/*! \name Object Containers
 * Here start declarations of containers.
 *
 * @{
 */
struct ao2_container;
 
/*!
 * \brief Allocate and initialize a hash container with the desired number of buckets.
 *
 * \details
 * We allocate space for a struct astobj_container, struct container
 * and the buckets[] array.
 *
 * \param ao2_options Container ao2 object options (See enum ao2_alloc_opts)
 * \param container_options Container behaviour options (See enum ao2_container_opts)
 * \param n_buckets Number of buckets for hash
 * \param hash_fn Pointer to a function computing a hash value. (NULL if everyting goes in first bucket.)
 * \param sort_fn Pointer to a sort function. (NULL to not sort the buckets.)
 * \param cmp_fn Pointer to a compare function used by ao2_find. (NULL to match everything)
 *
 * \return A pointer to a struct container.
 *
 * \note Destructor is set implicitly.
 */
#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__)
 
#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__)
 
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;
 
/*!
 * \brief Allocate and initialize a list container.
 *
 * \param ao2_options Container ao2 object options (See enum ao2_alloc_opts)
 * \param container_options Container behaviour options (See enum ao2_container_opts)
 * \param sort_fn Pointer to a sort function. (NULL if list not sorted.)
 * \param cmp_fn Pointer to a compare function used by ao2_find. (NULL to match everything)
 *
 * \return A pointer to a struct container.
 *
 * \note Destructor is set implicitly.
 * \note Implemented as a degenerate hash table.
 */
#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__)
 
#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__)
 
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;
 
/*!
 * \brief Allocate and initialize a red-black tree container.
 *
 * \param ao2_options Container ao2 object options (See enum ao2_alloc_opts)
 * \param container_options Container behaviour options (See enum ao2_container_opts)
 * \param sort_fn Pointer to a sort function.
 * \param cmp_fn Pointer to a compare function used by ao2_find. (NULL to match everything)
 *
 * \return A pointer to a struct container.
 *
 * \note Destructor is set implicitly.
 */
#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__)
 
#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__)
 
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;
 
/*! \brief
 * Returns the number of elements in a container.
 */
int ao2_container_count(struct ao2_container *c);
 
/*!
 * \brief Copy all object references in the src container into the dest container.
 * \since 11.0
 *
 * \param dest Container to copy src object references into.
 * \param src Container to copy all object references from.
 * \param flags OBJ_NOLOCK if a lock is already held on both containers.
 *    Otherwise, the src container is locked first.
 *
 * \pre 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.
 *
 * \retval 0 on success.
 * \retval -1 on error.
 */
int ao2_container_dup(struct ao2_container *dest, struct ao2_container *src, enum search_flags flags);
 
/*!
 * \brief Copy object references associated with src container weakproxies into the dest container.
 *
 * \param dest Container to copy src strong object references into.
 * \param src Container to copy all weak object references from.
 * \param flags OBJ_NOLOCK if a lock is already held on both containers.
 *    Otherwise, the src container is locked first.
 *
 * \pre 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.
 *
 * \note Every object inside the container is locked by \ref ao2_weakproxy_get_object.
 *       Any weakproxy in \p src with no associated object is ignored.
 *
 * \retval 0 on success.
 * \retval -1 on error.
 */
int ao2_container_dup_weakproxy_objs(struct ao2_container *dest, struct ao2_container *src, enum search_flags flags);
 
/*!
 * \brief Create a clone/copy of the given container.
 * \since 11.0
 *
 * \param orig Container to copy all object references from.
 * \param flags OBJ_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.
 *
 * \return Clone container on success.
 * \retval NULL on error.
 */
#define ao2_container_clone(orig, flags) \
    __ao2_container_clone(orig, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_t_container_clone(orig, flags, tag) \
    __ao2_container_clone(orig, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
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;
 
/*!
 * \brief Print output.
 * \since 12.0.0
 *
 * \param where User data pointer needed to determine where to put output.
 * \param fmt printf type format string.
 */
typedef void (ao2_prnt_fn)(void *where, const char *fmt, ...) __attribute__((format(printf, 2, 3)));
 
/*!
 * \brief Print object key.
 * \since 12.0.0
 *
 * \param v_obj A pointer to the object we want the key printed.
 * \param where User data needed by prnt to determine where to put output.
 * \param prnt Print output callback function to use.
 */
typedef void (ao2_prnt_obj_fn)(void *v_obj, void *where, ao2_prnt_fn *prnt);
 
/*!
 * \brief Display contents of the specified container.
 * \since 12.0.0
 *
 * \param self Container to dump.
 * \param flags OBJ_NOLOCK if a lock is already held on the container.
 * \param name Container name.  (NULL if anonymous)
 * \param where User data needed by prnt to determine where to put output.
 * \param prnt Print output callback function to use.
 * \param prnt_obj Callback function to print the given object's key. (NULL if not available)
 */
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);
 
/*!
 * \brief Display statistics of the specified container.
 * \since 12.0.0
 *
 * \param self Container to display statistics.
 * \param flags OBJ_NOLOCK if a lock is already held on the container.
 * \param name Container name.  (NULL if anonymous)
 * \param where User data needed by prnt to determine where to put output.
 * \param prnt Print output callback function to use.
 */
void ao2_container_stats(struct ao2_container *self, enum search_flags flags, const char *name, void *where, ao2_prnt_fn *prnt);
 
/*!
 * \brief Perform an integrity check on the specified container.
 * \since 12.0.0
 *
 * \param self Container to check integrity.
 * \param flags OBJ_NOLOCK if a lock is already held on the container.
 *
 * \retval 0 on success.
 * \retval -1 on error.
 */
int ao2_container_check(struct ao2_container *self, enum search_flags flags);
 
/*!
 * \brief Register a container for CLI stats and integrity check.
 * \since 12.0.0
 *
 * \param name Name to register the container under.
 * \param self Container to register.
 * \param prnt_obj Callback function to print the given object's key. (NULL if not available)
 *
 * \retval 0 on success.
 * \retval -1 on error.
 */
int ao2_container_register(const char *name, struct ao2_container *self, ao2_prnt_obj_fn *prnt_obj);
 
/*!
 * \brief Unregister a container for CLI stats and integrity check.
 * \since 12.0.0
 *
 * \param name Name the container is registered under.
 */
void ao2_container_unregister(const char *name);
 
/*! @} */
 
/*! \name Object Management
 * Here we have functions to manage objects.
 *
 * We can use the functions below on any kind of
 * object defined by the user.
 *
 * @{
 */
 
/*!
 * \brief Add an object to a container.
 *
 * \param container The container to operate on.
 * \param obj The object to be added.
 *
 * \retval 0 on errors.
 * \retval 1 on success.
 *
 * This function inserts an object in a container according its key.
 *
 * \note Remember to set the key before calling this function.
 *
 * \note This function automatically increases the reference count to account
 *       for the reference that the container now holds to the object.
 */
#define ao2_link(container, obj) \
    __ao2_link((container), (obj), 0, NULL,  __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_link(container, obj, tag) \
    __ao2_link((container), (obj), 0, (tag),  __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
/*!
 * \brief Add an object to a container.
 *
 * \param container The container to operate on.
 * \param obj The object to be added.
 * \param flags search_flags to control linking the object.  (OBJ_NOLOCK)
 *
 * \retval 0 on errors.
 * \retval 1 on success.
 *
 * This function inserts an object in a container according its key.
 *
 * \note Remember to set the key before calling this function.
 *
 * \note This function automatically increases the reference count to account
 *       for the reference that the container now holds to the object.
 */
#define ao2_link_flags(container, obj, flags) \
    __ao2_link((container), (obj), (flags), NULL,  __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_link_flags(container, obj, flags, tag) \
    __ao2_link((container), (obj), (flags), (tag),  __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
int __ao2_link(struct ao2_container *c, void *obj_new, int flags,
    const char *tag, const char *file, int line, const char *func);
 
/*!
 * \brief Remove an object from a container
 *
 * \param container The container to operate on.
 * \param obj The object to unlink.
 *
 * \retval NULL always
 *
 * \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.
 *
 * \note If the object gets unlinked from the container, the container's
 *       reference to the object will be automatically released. (The
 *       refcount will be decremented).
 */
#define ao2_unlink(container, obj) \
    __ao2_unlink((container), (obj), 0, NULL,  __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_unlink(container, obj, tag) \
    __ao2_unlink((container), (obj), 0, (tag),  __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
/*!
 * \brief Remove an object from a container
 *
 * \param container The container to operate on.
 * \param obj The object to unlink.
 * \param flags search_flags to control unlinking the object.  (OBJ_NOLOCK)
 *
 * \retval NULL always
 *
 * \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.
 *
 * \note If the object gets unlinked from the container, the container's
 *       reference to the object will be automatically released. (The
 *       refcount will be decremented).
 */
#define ao2_unlink_flags(container, obj, flags) \
    __ao2_unlink((container), (obj), (flags), NULL,  __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_t_unlink_flags(container, obj, flags, tag) \
    __ao2_unlink((container), (obj), (flags), (tag),  __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
void *__ao2_unlink(struct ao2_container *c, void *obj, int flags,
    const char *tag, const char *file, int line, const char *func);
 
/*! @} */
 
 
/*! \brief
 * ao2_callback() is a generic function that applies cb_fn() to all objects
 * in a container, as described below.
 *
 * \param c A pointer to the container to operate on.
 * \param flags A 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.
 * \param cb_fn A 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).
 * \param arg passed to the callback.
 *
 * \retval NULL on failure or no matching object found.
 *
 * \return object found if OBJ_MULTIPLE is not set in the flags
 * parameter.
 *
 * \return 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.
 *
 * @{
 */
#define ao2_callback(c, flags, cb_fn, arg) \
    __ao2_callback((c), (flags), (cb_fn), (arg), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ao2_t_callback(c, flags, cb_fn, arg, tag) \
    __ao2_callback((c), (flags), (cb_fn), (arg), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
void *__ao2_callback(struct ao2_container *c, enum search_flags flags,
    ao2_callback_fn *cb_fn, void *arg, const char *tag, const char *file, int line,
    const char *func);
 
/*! @} */
 
/*! \brief
 * 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 ao2_callback()
 */
 
#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__)
#define ao2_callback_data(container, flags, cb_fn, arg, data) \
    __ao2_callback_data((container), (flags), (cb_fn), (arg), (data), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
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);
 
/*! ao2_find() is a short hand for ao2_callback(c, flags, c->cmp_fn, arg)
 * XXX possibly change order of arguments ?
 */
 
#define ao2_t_find(container, arg, flags, tag) \
    __ao2_find((container), (arg), (flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_find(container, arg, flags) \
    __ao2_find((container), (arg), (flags), NULL, __FILE__, __LINE__, __PRETTY_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);
 
/*!
 * \brief 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 ao2_callback for description of arguments.
 */
#define ao2_weakproxy_find(c, arg, flags, tag) \
    __ao2_weakproxy_find(c, arg, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
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);
 
/*! \brief
 *
 *
 * When we need to walk through a container, we use an
 * ao2_iterator to keep track of the current position.
 *
 * Because the navigation is typically done without holding the
 * lock on the container across the loop, objects can be
 * inserted or deleted or moved while we work.  As a
 * consequence, there is no guarantee that we manage to touch
 * all the elements in the container, and it is possible that we
 * touch the same object multiple times.
 *
 * An iterator must be first initialized with
 * ao2_iterator_init(), then we can use o = ao2_iterator_next()
 * to move from one element to the next.  Remember that the
 * object returned by ao2_iterator_next() has its refcount
 * incremented, and the reference must be explicitly released
 * when done with it.
 *
 * In addition, ao2_iterator_init() will hold a reference to the
 * container being iterated and the last container node found.
 * These objects will be unreffed when ao2_iterator_destroy() is
 * called to free up the resources used by the iterator (if
 * any).
 *
 * Example:
 *
 *  \code
 *
 *  struct ao2_container *c = ... // the container we want to iterate on
 *  struct ao2_iterator i;
 *  struct my_obj *o;
 *
 *  i = ao2_iterator_init(c, flags);
 *
 *  while ((o = ao2_iterator_next(&i))) {
 *     ... do something on o ...
 *     ao2_ref(o, -1);
 *  }
 *
 *  ao2_iterator_restart(&i);
 *  while ((o = ao2_iterator_next(&i))) {
 *     ... do something on o ...
 *     ao2_ref(o, -1);
 *  }
 *
 *  ao2_iterator_destroy(&i);
 *
 *  \endcode
 *
 */
 
/*!
 * \brief The astobj2 iterator
 *
 * \note You are not supposed to know the internals of an iterator!
 * We would like the iterator to be opaque, unfortunately
 * its size needs to be known if we want to store it around
 * without too much trouble.
 * Anyways...
 * The iterator has a pointer to the container, and a flags
 * field specifying various things e.g. whether the container
 * should be locked or not while navigating on it.
 * The iterator "points" to the current container node.
 *
 * Details are in the implementation of ao2_iterator_next()
 */
struct ao2_iterator {
    /*! The container (Has a reference) */
    struct ao2_container *c;
    /*! Last container node (Has a reference) */
    void *last_node;
    /*! Nonzero if the iteration has completed. */
    int complete;
    /*! operation flags (enum ao2_iterator_flags) */
    int flags;
};
 
/*! Flags that can be passed to ao2_iterator_init() to modify the behavior
 * of the iterator.
 */
enum ao2_iterator_flags {
    /*!
     * \brief Assume that the ao2_container is already locked.
     *
     * \note For ao2_containers that have mutexes, no locking will
     * be done.
     *
     * \note 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.
     *
     * \note 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_DONTLOCK = (1 << 0),
    /*!
     * Indicates that the iterator was dynamically allocated by
     * astobj2 API and should be freed by ao2_iterator_destroy().
     */
    AO2_ITERATOR_MALLOCD = (1 << 1),
    /*!
     * Indicates that before the iterator returns an object from
     * the container being iterated, the object should be unlinked
     * from the container.
     */
    AO2_ITERATOR_UNLINK = (1 << 2),
    /*!
     * 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.
     */
    AO2_ITERATOR_DESCENDING = (1 << 3),
};
 
/*!
 * \brief Create an iterator for a container
 *
 * \param c the container
 * \param flags one or more flags from ao2_iterator_flags.
 *
 * \return the constructed iterator
 *
 * \note This function does \b 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.
 */
struct ao2_iterator ao2_iterator_init(struct ao2_container *c, int flags) attribute_warn_unused_result;
 
/*!
 * \brief Destroy a container iterator
 *
 * \param iter the iterator to destroy
 *
 * This function will release the container reference held by the iterator
 * and any other resources it may be holding.
 */
#if defined(TEST_FRAMEWORK)
void ao2_iterator_destroy(struct ao2_iterator *iter) __attribute__((noinline));
#else
void ao2_iterator_destroy(struct ao2_iterator *iter);
#endif  /* defined(TEST_FRAMEWORK) */
 
#define ao2_t_iterator_next(iter, tag) \
    __ao2_iterator_next((iter), (tag),  __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_iterator_next(iter) \
    __ao2_iterator_next((iter), NULL,  __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
void *__ao2_iterator_next(struct ao2_iterator *iter,
    const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result;
 
/*!
 * \brief Restart an iteration.
 *
 * \param iter the 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.
 */
void ao2_iterator_restart(struct ao2_iterator *iter);
 
/*! 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 */
void __ao2_cleanup(void *obj);
void __ao2_cleanup_debug(void *obj, const char *tag, const char *file, int line, const char *function);
#define ao2_cleanup(obj) __ao2_cleanup_debug((obj), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_cleanup(obj, tag) __ao2_cleanup_debug((obj), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
void ao2_iterator_cleanup(struct ao2_iterator *iter);
 
/*!
 * \brief Get a count of the iterated container objects.
 *
 * \param iter the iterator to query
 *
 * \return The number of objects in the iterated container
 */
int ao2_iterator_count(struct ao2_iterator *iter);
 
/*!
 * \brief Creates a hash function for a structure field.
 * \param stype The structure type
 * \param field The string field in the structure to hash
 * \param hash_fn Function 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.
 */
#define AO2_FIELD_HASH_FN(stype, field, hash_fn) \
static int stype ## _hash_fn(const void *obj, const int flags) \
{ \
    const struct stype *object = obj; \
    const char *key; \
    switch (flags & OBJ_SEARCH_MASK) { \
    case OBJ_SEARCH_KEY: \
        key = obj; \
        break; \
    case OBJ_SEARCH_OBJECT: \
        key = object->field; \
        break; \
    default: \
        ast_assert(0); \
        return 0; \
    } \
    return hash_fn(key); \
}
 
 
#define AO2_FIELD_TRANSFORM_CMP_FN(cmp) ((cmp) ? 0 : CMP_MATCH)
#define AO2_FIELD_TRANSFORM_SORT_FN(cmp) (cmp)
 
/*!
 * \internal
 *
 * \brief Creates a compare function for a structure string field.
 * \param stype The structure type
 * \param fn_suffix Function name suffix
 * \param field The string field in the structure to compare
 * \param key_cmp Key comparison function like strcmp
 * \param partial_key_cmp Partial key comparison function like strncmp
 * \param transform A macro that takes the cmp result as an argument
 *                  and transforms it to a return value.
 * \param argconst
 *
 * Do not use this macro directly, instead use macro's starting with
 * AST_STRING_FIELD.
 *
 * \warning The macro is an internal implementation detail, the API
 *          may change at any time.
 */
#define AO2_FIELD_CMP_FN(stype, fn_suffix, field, key_cmp, partial_key_cmp, transform, argconst) \
static int stype ## fn_suffix(argconst void *obj, argconst void *arg, int flags) \
{ \
    const struct stype *object_left = obj, *object_right = arg; \
    const char *right_key = arg; \
    int cmp; \
    switch (flags & OBJ_SEARCH_MASK) { \
    case OBJ_SEARCH_OBJECT: \
        right_key = object_right->field; \
    case OBJ_SEARCH_KEY: \
        cmp = key_cmp(object_left->field, right_key); \
        break; \
    case OBJ_SEARCH_PARTIAL_KEY: \
        cmp = partial_key_cmp(object_left->field, right_key, strlen(right_key)); \
        break; \
    default: \
        cmp = 0; \
        break; \
    } \
    return transform(cmp); \
}
 
/*!
 * \brief Creates a hash function for a structure string field.
 * \param stype The structure type
 * \param field The 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.
 */
#define AO2_STRING_FIELD_HASH_FN(stype, field) \
    AO2_FIELD_HASH_FN(stype, field, ast_str_hash)
#define AO2_STRING_FIELD_CASE_HASH_FN(stype, field) \
    AO2_FIELD_HASH_FN(stype, field, ast_str_case_hash)
 
/*!
 * \brief Creates a compare function for a structure string field.
 * \param stype The structure type
 * \param field The 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.
 */
#define AO2_STRING_FIELD_CMP_FN(stype, field) \
    AO2_FIELD_CMP_FN(stype, _cmp_fn, field, strcmp, strncmp, AO2_FIELD_TRANSFORM_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,)
 
/*!
 * \brief Creates a sort function for a structure string field.
 * \param stype The structure type
 * \param field The 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.
 */
#define AO2_STRING_FIELD_SORT_FN(stype, field) \
    AO2_FIELD_CMP_FN(stype, _sort_fn, field, strcmp, strncmp, AO2_FIELD_TRANSFORM_SORT_FN, const)
#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)
 
#endif /* _ASTERISK_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_size	The sizeof() of the user-defined structure.
destructor_fn	The destructor function (can be NULL)
lockobj	A separate ao2 object that will provide locking.
tag	An 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

obj	AO2 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

c	A pointer to the container to operate on.
flags	A 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_fn	A 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).
arg	passed to the callback.

Return values

NULL	on 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_options	Container ao2 object options (See enum ao2_alloc_opts)
container_options	Container behaviour options (See enum ao2_container_opts)
n_buckets	Number of buckets for hash
hash_fn	Pointer to a function computing a hash value. (NULL if everyting goes in first bucket.)
sort_fn	Pointer to a sort function. (NULL to not sort the buckets.)
cmp_fn	Pointer 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_options	Container ao2 object options (See enum ao2_alloc_opts)
container_options	Container behaviour options (See enum ao2_container_opts)
sort_fn	Pointer to a sort function. (NULL if list not sorted.)
cmp_fn	Pointer 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_options	Container ao2 object options (See enum ao2_alloc_opts)
container_options	Container behaviour options (See enum ao2_container_opts)
sort_fn	Pointer to a sort function.
cmp_fn	Pointer 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

orig	Container to copy all object references from.
flags	OBJ_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

NULL

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

{ \
    const struct stype *object_left = obj, *object_right = arg; \
    const char *right_key = arg; \
    int cmp; \
    switch (flags & OBJ_SEARCH_MASK) { \
    case OBJ_SEARCH_OBJECT: \
        right_key = object_right->field; \
    case OBJ_SEARCH_KEY: \
        cmp = key_cmp(object_left->field, right_key); \
        break; \
    case OBJ_SEARCH_PARTIAL_KEY: \
        cmp = partial_key_cmp(object_left->field, right_key, strlen(right_key)); \
        break; \
    default: \
        cmp = 0; \
        break; \
    } \
    return transform(cmp); \
}

AO2_FIELD_HASH_FN

#define AO2_FIELD_HASH_FN	(		stype,
			field,
			hash_fn
	)

Creates a hash function for a structure field.

Parameters

stype	The structure type
field	The string field in the structure to hash
hash_fn	Function 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.

{ \
    const struct stype *object = obj; \
    const char *key; \
    switch (flags & OBJ_SEARCH_MASK) { \
    case OBJ_SEARCH_KEY: \
        key = obj; \
        break; \
    case OBJ_SEARCH_OBJECT: \
        key = object->field; \
        break; \
    default: \
        ast_assert(0); \
        return 0; \
    } \
    return hash_fn(key); \
}

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

obj	The 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

holder

Global ao2 object holder.

Returns

Reference to current ao2 object stored in the holder.

Return values

NULL	if 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

holder

Global 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

holder	Global ao2 object holder.
obj	Object 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

NULL	if 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

holder	Global ao2 object holder.
obj	Object 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

0	The global object was previously empty
1	The 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 = {                                      \
        .lock = AST_RWLOCK_INIT_VALUE,                                  \
    }

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

Since

11.0

Parameters

name	This 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);

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

Examples

app_skel.c.

Definition at line 847 of file astobj2.h.

                                 {                                      \
        .lock = AST_RWLOCK_INIT_VALUE,                                  \
    }

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

container	The container to operate on.
obj	The object to be added.

Return values

0	on errors.
1	on 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

container	The container to operate on.
obj	The object to be added.
flags	search_flags to control linking the object. (OBJ_NOLOCK)

Return values

0	on errors.
1	on 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

o	A pointer to the object
delta	Value 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

dst	Pointer to the object that will be cleaned up.
src	Pointer 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

stype	The structure type
field	The 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

stype	The structure type
field	The 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

stype	The structure type
field	The 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_size	The sizeof() of the user-defined structure.
destructor_fn	The destructor function (can be NULL)
options	The ao2 object options (See enum ao2_alloc_opts)
debug_msg	An 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.

     {                          \
        typeof(obj) __obj_ ## __LINE__ = (obj);     \
        if (__obj_ ## __LINE__) {           \
            ao2_t_ref(__obj_ ## __LINE__, +1, (tag));   \
        }                       \
        __obj_ ## __LINE__;             \
    })

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.

    {\
        typeof(dst) *__dst_ ## __LINE__ = &dst; \
        typeof(src) __src_ ## __LINE__ = src; \
        if (__src_ ## __LINE__ != *__dst_ ## __LINE__) { \
            if (__src_ ## __LINE__) {\
                ao2_t_ref(__src_ ## __LINE__, +1, (tag)); \
            } \
            if (*__dst_ ## __LINE__) {\
                ao2_t_ref(*__dst_ ## __LINE__, -1, (tag)); \
            } \
            *__dst_ ## __LINE__ = __src_ ## __LINE__; \
        } \
    }

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

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

container	The container to operate on.
obj	The object to unlink.

Return values

NULL

always

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

container	The container to operate on.
obj	The object to unlink.
flags	search_flags to control unlinking the object. (OBJ_NOLOCK)

Return values

NULL

always

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_size	The sizeof() of the user-defined structure.
destructor_fn	The 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

weakproxy	The weakproxy to read from.
flags	OBJ_NOLOCK to avoid locking weakproxy.

Returns

A reference to the object previously set by ao2_weakproxy_set_object.

Return values

NULL	Either 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

weakproxy	The weakproxy to read from.
delta	Value to add to the reference counter.
flags	OBJ_NOLOCK to avoid locking weakproxy.

Return values

-2	weakproxy is not a valid ao2_weakproxy.
-1	weakproxy 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

weakproxy	An object created by ao2_weakproxy_alloc.
obj	An ao2 object not created by ao2_weakproxy_alloc.
flags	OBJ_NOLOCK to avoid locking weakproxy.

Return values

0	Success
-1	Failure

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

obj	pointer to the (user-defined part) of an object.
arg	callback argument from ao2_callback()
data	arbitrary data from ao2_callback()
flags	flags 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

obj	pointer to the (user-defined part) of an object.
arg	callback argument from ao2_callback()
flags	flags 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

vdoomed

Object 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

obj	pointer to the (user-defined part) of an object.
flags	flags 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

where	User data pointer needed to determine where to put output.
fmt	printf 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_obj	A pointer to the object we want the key printed.
where	User data needed by prnt to determine where to put output.
prnt	Print 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_left	pointer to the (user-defined part) of an object.
obj_right	pointer to the (user-defined part) of an object.
flags	flags 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

negtaive	if obj_left < obj_right
0	if obj_left == obj_right
positive	if 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

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

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

ao2_alloc_opts

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

                    {
    /*! The ao2 object has a recursive mutex lock associated with it. */
    AO2_ALLOC_OPT_LOCK_MUTEX = (0 << 0),
    /*! The ao2 object has a non-recursive read/write lock associated with it. */
    AO2_ALLOC_OPT_LOCK_RWLOCK = (1 << 0),
    /*! The ao2 object has no lock associated with it. */
    AO2_ALLOC_OPT_LOCK_NOLOCK = (2 << 0),
    /*! The ao2 object locking option field mask. */
    AO2_ALLOC_OPT_LOCK_MASK = (3 << 0),
    /*!
     * \internal The ao2 object uses a separate object for locking.
     *
     * \note This option is used internally by ao2_alloc_with_lockobj and
     * should never be passed directly to ao2_alloc.
     */
    AO2_ALLOC_OPT_LOCK_OBJ = AO2_ALLOC_OPT_LOCK_MASK,
    /*! The ao2 object will not record any REF_DEBUG entries */
    AO2_ALLOC_OPT_NO_REF_DEBUG = (1 << 2),
};

ao2_container_opts

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

                        {
    /*!
     * \brief 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.
     *
     * \note Hash containers insert the object in the computed hash
     * bucket in the indicated manner.
     */
    AO2_CONTAINER_ALLOC_OPT_INSERT_BEGIN = (1 << 0),
 
    /*!
     * \brief The ao2 container objects with duplicate keys option field mask.
     */
    AO2_CONTAINER_ALLOC_OPT_DUPS_MASK = (3 << 1),
    /*!
     * \brief Allow objects with duplicate keys in container.
     */
    AO2_CONTAINER_ALLOC_OPT_DUPS_ALLOW = (0 << 1),
    /*!
     * \brief 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_REJECT = (1 << 1),
    /*!
     * \brief Reject duplicate objects in container.
     *
     * \details 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.
     *
     * \note It is assumed that the objects are located where the
     * search key says they should be located.
     */
    AO2_CONTAINER_ALLOC_OPT_DUPS_OBJ_REJECT = (2 << 1),
    /*!
     * \brief Replace objects with duplicate keys in container.
     *
     * \details 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.
     */
    AO2_CONTAINER_ALLOC_OPT_DUPS_REPLACE = (3 << 1),
};

ao2_iterator_flags

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

                        {
    /*!
     * \brief Assume that the ao2_container is already locked.
     *
     * \note For ao2_containers that have mutexes, no locking will
     * be done.
     *
     * \note 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.
     *
     * \note 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_DONTLOCK = (1 << 0),
    /*!
     * Indicates that the iterator was dynamically allocated by
     * astobj2 API and should be freed by ao2_iterator_destroy().
     */
    AO2_ITERATOR_MALLOCD = (1 << 1),
    /*!
     * Indicates that before the iterator returns an object from
     * the container being iterated, the object should be unlinked
     * from the container.
     */
    AO2_ITERATOR_UNLINK = (1 << 2),
    /*!
     * 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.
     */
    AO2_ITERATOR_DESCENDING = (1 << 3),
};

ao2_lock_req

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

                  {
    /*! Request the mutex lock be acquired. */
    AO2_LOCK_REQ_MUTEX,
    /*! Request the read lock be acquired. */
    AO2_LOCK_REQ_RDLOCK,
    /*! Request the write lock be acquired. */
    AO2_LOCK_REQ_WRLOCK,
};

search_flags

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

                  {
    /*!
     * Unlink the object for which the callback function returned
     * CMP_MATCH.
     */
    OBJ_UNLINK = (1 << 0),
    /*!
     * On match, don't return the object hence do not increase its
     * refcount.
     */
    OBJ_NODATA = (1 << 1),
    /*!
     * Don't stop at the first match in ao2_callback() unless the
     * result of the callback function has the CMP_STOP bit set.
     */
    OBJ_MULTIPLE = (1 << 2),
    /*!
     * \brief Assume that the ao2_container is already locked.
     *
     * \note For ao2_containers that have mutexes, no locking will
     * be done.
     *
     * \note 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.
     *
     * \note Only use this flag if the ao2_container is manually
     * locked already.
     */
    OBJ_NOLOCK = (1 << 4),
 
    /*!
     * \brief 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_MASK = (0x07 << 5),
    /*! \brief The arg parameter has no meaning to the astobj2 code. */
    OBJ_SEARCH_NONE = (0 << 5),
    /*!
     * \brief The arg parameter is an object of the same type.
     *
     * \details
     * 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_OBJECT = (1 << 5),
    /*!
     * \brief The arg parameter is a search key, but is not an object.
     *
     * \details
     * 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_KEY = (2 << 5),
    /*!
     * \brief The arg parameter is a partial search key similar to OBJ_SEARCH_KEY.
     *
     * \details
     * 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_SEARCH_PARTIAL_KEY = (4 << 5),
 
    /*! \brief Traverse order option field mask. */
    OBJ_ORDER_MASK = (0x03 << 8),
    /*! \brief Traverse in ascending order (First to last container object) */
    OBJ_ORDER_ASCENDING = (0 << 8),
    /*! \brief Traverse in descending order (Last to first container object) */
    OBJ_ORDER_DESCENDING = (1 << 8),
    /*!
     * \brief 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_PRE = (2 << 8),
    /*!
     * \brief 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.
     */
    OBJ_ORDER_POST = (3 << 8),
};

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.

{
    return internal_ao2_alloc(data_size, destructor_fn, options, NULL, tag, file, line, func);
}

References internal_ao2_alloc(), NULL, and options.

Referenced by __ao2_container_alloc_hash(), __ao2_container_alloc_rbtree(), __ao2_weakproxy_alloc(), __ast_channel_internal_alloc_with_initializers(), __ast_format_cap_alloc(), __ast_named_lock_get(), __ast_sorcery_open(), _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.

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

References AO2_ALLOC_OPT_LOCK_OBJ, 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.

{
    return internal_ao2_traverse(c, flags, cb_fn, arg, NULL, AO2_CALLBACK_DEFAULT, tag, file, line, func);
}

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

Referenced by __ao2_find(), and __ao2_unlink().

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

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

References AO2_CALLBACK_WITH_DATA, c, 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.

{
    if (obj) {
        ao2_ref(obj, -1);
    }
}

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(), parking_set_duration(), and speech_observer_loaded().

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

{
    if (obj) {
        __ao2_ref(obj, -1, tag, file, line, function);
    }
}

References __ao2_ref().

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

{
    unsigned int num_buckets;
    size_t container_size;
    struct ao2_container_hash *self;
 
    num_buckets = hash_fn ? n_buckets : 1;
    container_size = sizeof(struct ao2_container_hash) + num_buckets * sizeof(struct hash_bucket);
 
    self = __ao2_alloc(container_size, container_destruct, ao2_options,
        tag ?: __PRETTY_FUNCTION__, file, line, func);
    return hash_ao2_container_init(self, container_options, num_buckets, hash_fn,
        sort_fn, cmp_fn);
}

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

Referenced by __ao2_container_alloc_list(), and 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.

{
    return __ao2_container_alloc_hash(ao2_options, container_options, 1, NULL,
        sort_fn, cmp_fn, tag, file, line, func);
}

References __ao2_container_alloc_hash(), ao2_container::cmp_fn, NULL, and ao2_container::sort_fn.

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

{
    struct ao2_container_rbtree *self;
 
    if (!sort_fn) {
        /* Sanity checks. */
        ast_log(__LOG_ERROR, file, line, func, "Missing sort_fn()!\n");
        return NULL;
    }
 
    self = __ao2_alloc(sizeof(*self), container_destruct, ao2_options,
        tag ?: __PRETTY_FUNCTION__, file, line, func);
    return rb_ao2_container_init(self, container_options, sort_fn, cmp_fn);
}

References __ao2_alloc(), __LOG_ERROR, ast_log, container_destruct(), NULL, and rb_ao2_container_init().

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.

{
    struct ao2_container *clone;
    int failed;
 
    /* Create the clone container with the same properties as the original. */
    if (!__is_ao2_object(orig, file, line, func)) {
        return NULL;
    }
 
    if (!orig->v_table || !orig->v_table->alloc_empty_clone) {
        /* Sanity checks. */
        __ast_assert_failed(0, "invalid container v_table", file, line, func);
        return NULL;
    }
 
    clone = orig->v_table->alloc_empty_clone(orig, tag, file, line, func);
    if (!clone) {
        return NULL;
    }
 
    /* This test is correct.  clone must be locked before calling
     * ao2_container_dup when the OBJ_NOLOCK flag is set, otherwise
     * we could have errors in __adjust_lock. */
    if (flags & OBJ_NOLOCK) {
        ao2_wrlock(clone);
    }
    failed = ao2_container_dup(clone, orig, flags);
    if (flags & OBJ_NOLOCK) {
        ao2_unlock(clone);
    }
    if (failed) {
        /* Object copy into the clone container failed. */
        __ao2_ref(clone, -1, tag ?: "Clone creation failed", file, line, func);
        clone = NULL;
    }
    return clone;
}

References __ao2_ref(), __ast_assert_failed(), __is_ao2_object, ao2_container_methods::alloc_empty_clone, ao2_container_dup(), ao2_unlock, ao2_wrlock, 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.

{
    void *arged = (void *) arg;/* Done to avoid compiler const warning */
 
    if (!c) {
        /* Sanity checks. */
        ast_assert(0);
        return NULL;
    }
    return __ao2_callback(c, flags, c->cmp_fn, arged, tag, file, line, func);
}

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

Referenced by __ast_format_cache_get(), 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.

{
    struct astobj2 *obj_internal = __INTERNAL_OBJ_CHECK(obj, file, line, func);
 
    if (!obj_internal || obj_internal->priv_data.magic != AO2_MAGIC) {
        /* This method is meant to be run on normal ao2 objects! */
        return NULL;
    }
 
    if (!obj_internal->priv_data.weakptr) {
        return NULL;
    }
 
    __ao2_ref(obj_internal->priv_data.weakptr, +1, tag, file, line, func);
    return obj_internal->priv_data.weakptr;
}

References __ao2_ref(), __INTERNAL_OBJ_CHECK, AO2_MAGIC, __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.

{
    void *obj;
 
    if (!holder) {
        /* For sanity */
        ast_log(LOG_ERROR, "Must be called with a global object!\n");
        ast_assert(0);
        return NULL;
    }
 
    if (__ast_rwlock_rdlock(file, line, func, &holder->lock, name)) {
        /* Could not get the read lock. */
        ast_assert(0);
        return NULL;
    }
 
    obj = holder->obj;
    if (obj) {
        __ao2_ref(obj, +1, tag, file, line, func);
    }
 
    __ast_rwlock_unlock(file, line, func, &holder->lock, name);
 
    return obj;
}

References __ao2_ref(), __ast_rwlock_rdlock(), __ast_rwlock_unlock(), ast_assert, ast_log, 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.

{
    void *obj_old;
 
    if (!holder) {
        /* For sanity */
        ast_log(LOG_ERROR, "Must be called with a global object!\n");
        ast_assert(0);
        return NULL;
    }
    if (__ast_rwlock_wrlock(file, line, func, &holder->lock, name)) {
        /* Could not get the write lock. */
        ast_assert(0);
        return NULL;
    }
 
    if (obj) {
        __ao2_ref(obj, +1, tag, file, line, func);
    }
    obj_old = holder->obj;
    holder->obj = obj;
 
    __ast_rwlock_unlock(file, line, func, &holder->lock, name);
 
    return obj_old;
}

References __ao2_ref(), __ast_rwlock_unlock(), __ast_rwlock_wrlock(), ast_assert, ast_log, 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.

{
    void *obj_old;
 
    obj_old = __ao2_global_obj_replace(holder, obj, tag, file, line, func, name);
    if (obj_old) {
        __ao2_ref(obj_old, -1, tag, file, line, func);
        return 1;
    }
    return 0;
}

References __ao2_global_obj_replace(), __ao2_ref(), 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.

{
    enum ao2_lock_req orig_lock;
    struct ao2_container_node *node;
    void *ret;
 
    if (!__is_ao2_object(iter->c, file, line, func)) {
        return NULL;
    }
 
    if (!iter->c->v_table || !iter->c->v_table->iterator_next) {
        /* Sanity checks. */
        __ast_assert_failed(0, "invalid iterator container v_table", file, line, func);
        return NULL;
    }
 
    if (iter->complete) {
        /* Don't return any more objects. */
        return NULL;
    }
 
    if (iter->flags & AO2_ITERATOR_DONTLOCK) {
        if (iter->flags & AO2_ITERATOR_UNLINK) {
            orig_lock = __adjust_lock(iter->c, AO2_LOCK_REQ_WRLOCK, 1);
        } else {
            orig_lock = __adjust_lock(iter->c, AO2_LOCK_REQ_RDLOCK, 1);
        }
    } else {
        orig_lock = AO2_LOCK_REQ_MUTEX;
        if (iter->flags & AO2_ITERATOR_UNLINK) {
            ao2_wrlock(iter->c);
        } else {
            ao2_rdlock(iter->c);
        }
    }
 
    node = iter->c->v_table->iterator_next(iter->c, iter->last_node, iter->flags);
    if (node) {
        ret = node->obj;
 
        if (iter->flags & AO2_ITERATOR_UNLINK) {
            /* Transfer the object ref from the container to the returned object. */
            __container_unlink_node_debug(node, AO2_UNLINK_NODE_DEC_COUNT, tag, file, line, func);
 
            /* Transfer the container's node ref to the iterator. */
        } else {
            /* Bump ref of returned object */
            __ao2_ref(ret, +1, tag ?: "Next iterator object.", file, line, func);
 
            /* Bump the container's node ref for the iterator. */
            ao2_ref(node, +1);
        }
    } else {
        /* The iteration has completed. */
        iter->complete = 1;
        ret = NULL;
    }
 
    /* Replace the iterator's node */
    if (iter->last_node) {
        ao2_ref(iter->last_node, -1);
    }
    iter->last_node = node;
 
    if (iter->flags & AO2_ITERATOR_DONTLOCK) {
        __adjust_lock(iter->c, orig_lock, 0);
    } else {
        ao2_unlock(iter->c);
    }
 
    return ret;
}

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

{
    int res;
    enum ao2_lock_req orig_lock;
    struct ao2_container_node *node;
 
    if (!__is_ao2_object(obj_new, file, line, func)
        || !__is_ao2_object(self, file, line, func)) {
        return 0;
    }
 
    if (!self->v_table || !self->v_table->new_node || !self->v_table->insert) {
        /* Sanity checks. */
        __ast_assert_failed(0, "invalid container v_table", file, line, func);
        return 0;
    }
 
    if (flags & OBJ_NOLOCK) {
        orig_lock = __adjust_lock(self, AO2_LOCK_REQ_WRLOCK, 1);
    } else {
        ao2_wrlock(self);
        orig_lock = AO2_LOCK_REQ_MUTEX;
    }
 
    res = 0;
    node = self->v_table->new_node(self, obj_new, tag, file, line, func);
    if (node) {
#if defined(AO2_DEBUG)
        if (ao2_container_check(self, OBJ_NOLOCK)) {
            ast_log(LOG_ERROR, "Container integrity failed before insert.\n");
        }
#endif  /* defined(AO2_DEBUG) */
 
        /* Insert the new node. */
        switch (self->v_table->insert(self, node)) {
        case AO2_CONTAINER_INSERT_NODE_INSERTED:
            node->is_linked = 1;
            ast_atomic_fetchadd_int(&self->elements, 1);
#if defined(AO2_DEBUG)
            AO2_DEVMODE_STAT(++self->nodes);
            if (self->v_table->link_stat) {
                self->v_table->link_stat(self, node);
            }
#endif  /* defined(AO2_DEBUG) */
            /* Fall through */
        case AO2_CONTAINER_INSERT_NODE_OBJ_REPLACED:
#if defined(AO2_DEBUG)
            if (ao2_container_check(self, OBJ_NOLOCK)) {
                ast_log(LOG_ERROR, "Container integrity failed after insert or replace.\n");
            }
#endif  /* defined(AO2_DEBUG) */
            res = 1;
            break;
        case AO2_CONTAINER_INSERT_NODE_REJECTED:
            ao2_ref(node, -1);
            break;
        }
    }
 
    if (flags & OBJ_NOLOCK) {
        __adjust_lock(self, orig_lock, 0);
    } else {
        ao2_unlock(self);
    }
 
    return res;
}

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, ao2_container::elements, ao2_container_methods::insert, LOG_ERROR, ao2_container_methods::new_node, OBJ_NOLOCK, and ao2_container::v_table.

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

a	A 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.

{
    struct astobj2 *obj = __INTERNAL_OBJ_CHECK(user_data, file, line, func);
    struct astobj2_lock *obj_mutex;
    struct astobj2_rwlock *obj_rwlock;
    struct astobj2_lockobj *obj_lockobj;
    int res = 0;
 
    if (obj == NULL) {
        return -1;
    }
 
    if (ref_log) {
        obj->priv_data.lockused  = 1;
    }
 
    switch (obj->priv_data.options & AO2_ALLOC_OPT_LOCK_MASK) {
    case AO2_ALLOC_OPT_LOCK_MUTEX:
        obj_mutex = INTERNAL_OBJ_MUTEX(user_data);
        res = __ast_pthread_mutex_lock(file, line, func, var, &obj_mutex->mutex.lock);
#ifdef AO2_DEBUG
        if (!res) {
            ast_atomic_fetchadd_int(&ao2.total_locked, 1);
        }
#endif
        break;
    case AO2_ALLOC_OPT_LOCK_RWLOCK:
        obj_rwlock = INTERNAL_OBJ_RWLOCK(user_data);
        switch (lock_how) {
        case AO2_LOCK_REQ_MUTEX:
        case AO2_LOCK_REQ_WRLOCK:
            res = __ast_rwlock_wrlock(file, line, func, &obj_rwlock->rwlock.lock, var);
            if (!res) {
                ast_atomic_fetchadd_int(&obj_rwlock->rwlock.num_lockers, -1);
#ifdef AO2_DEBUG
                ast_atomic_fetchadd_int(&ao2.total_locked, 1);
#endif
            }
            break;
        case AO2_LOCK_REQ_RDLOCK:
            res = __ast_rwlock_rdlock(file, line, func, &obj_rwlock->rwlock.lock, var);
            if (!res) {
                ast_atomic_fetchadd_int(&obj_rwlock->rwlock.num_lockers, +1);
#ifdef AO2_DEBUG
                ast_atomic_fetchadd_int(&ao2.total_locked, 1);
#endif
            }
            break;
        }
        break;
    case AO2_ALLOC_OPT_LOCK_NOLOCK:
        /* The ao2 object has no lock. */
        break;
    case AO2_ALLOC_OPT_LOCK_OBJ:
        obj_lockobj = INTERNAL_OBJ_LOCKOBJ(user_data);
        res = __ao2_lock(obj_lockobj->lockobj.lock, lock_how, file, func, line, var);
        break;
    default:
        ast_log(__LOG_ERROR, file, line, func, "Invalid lock option on ao2 object %p\n",
            user_data);
        return -1;
    }
 
    return res;
}

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

{
    struct astobj2 *obj = __INTERNAL_OBJ_CHECK(user_data, file, line, func);
    struct astobj2_lock *obj_mutex;
    struct astobj2_rwlock *obj_rwlock;
    struct astobj2_lockobj *obj_lockobj;
    int32_t current_value;
    int32_t ret;
    uint32_t privdataoptions;
    struct ao2_weakproxy *weakproxy = NULL;
    const char *lock_state;
 
    if (obj == NULL) {
        if (ref_log && user_data) {
            fprintf(ref_log, "%p,%d,%d,%s,%d,%s,**invalid**,%s\n",
                user_data, delta, ast_get_tid(), file, line, func, tag ?: "");
            fflush(ref_log);
        }
        return -1;
    }
 
    /* if delta is 0, just return the refcount */
    if (delta == 0) {
        return obj->priv_data.ref_counter;
    }
 
    if (delta < 0 && obj->priv_data.magic == AO2_MAGIC && (weakproxy = obj->priv_data.weakptr)) {
        ao2_lock(weakproxy);
    }
 
    /* we modify with an atomic operation the reference counter */
    ret = ast_atomic_fetch_add(&obj->priv_data.ref_counter, delta, __ATOMIC_RELAXED);
    current_value = ret + delta;
 
#ifdef AO2_DEBUG
    ast_atomic_fetchadd_int(&ao2.total_refs, delta);
#endif
 
    if (weakproxy) {
        struct ao2_weakproxy cbs;
 
        if (current_value == 1) {
            /* The only remaining reference is the one owned by the weak object */
            struct astobj2 *internal_weakproxy;
 
            internal_weakproxy = INTERNAL_OBJ_CHECK(weakproxy);
 
            /* Unlink the obj from the weak proxy */
            internal_weakproxy->priv_data.weakptr = NULL;
            obj->priv_data.weakptr = NULL;
 
            /* transfer list to local copy so callbacks are run with weakproxy unlocked. */
            cbs.destroyed_cb = weakproxy->destroyed_cb;
            AST_LIST_HEAD_INIT_NOLOCK(&weakproxy->destroyed_cb);
 
            /* weak is already unlinked from obj so this won't recurse */
            ao2_ref(user_data, -1);
        }
 
        ao2_unlock(weakproxy);
 
        if (current_value == 1) {
            struct ao2_weakproxy_notification *destroyed_cb;
 
            /* Notify the subscribers that weakproxy now points to NULL. */
            while ((destroyed_cb = AST_LIST_REMOVE_HEAD(&cbs.destroyed_cb, list))) {
                destroyed_cb->cb(weakproxy, destroyed_cb->data);
                ast_free(destroyed_cb);
            }
 
            ao2_ref(weakproxy, -1);
        }
    }
 
    if (0 < current_value) {
        /* The object still lives. */
#define EXCESSIVE_REF_COUNT     100000
 
        if (EXCESSIVE_REF_COUNT <= current_value && ret < EXCESSIVE_REF_COUNT) {
            char excessive_ref_buf[100];
 
            /* We just reached or went over the excessive ref count trigger */
            snprintf(excessive_ref_buf, sizeof(excessive_ref_buf),
                "Excessive refcount %d reached on ao2 object %p",
                (int)current_value, user_data);
            ast_log(__LOG_ERROR, file, line, func, "%s\n", excessive_ref_buf);
 
            __ast_assert_failed(0, excessive_ref_buf, file, line, func);
        }
 
        if (ref_log && !(obj->priv_data.options & AO2_ALLOC_OPT_NO_REF_DEBUG)) {
            fprintf(ref_log, "%p,%s%d,%d,%s,%d,%s,%d,%s\n", user_data,
                (delta < 0 ? "" : "+"), delta, ast_get_tid(),
                file, line, func, (int)ret, tag ?: "");
            fflush(ref_log);
        }
        return ret;
    }
 
    /* this case must never happen */
    if (current_value < 0) {
        ast_log(__LOG_ERROR, file, line, func,
            "Invalid refcount %d on ao2 object %p\n", (int)current_value, user_data);
        if (ref_log) {
            /* Log to ref_log even if AO2_ALLOC_OPT_NO_REF_DEBUG */
            fprintf(ref_log, "%p,%d,%d,%s,%d,%s,**invalid**,%s\n",
                user_data, delta, ast_get_tid(), file, line, func, tag ?: "");
            fflush(ref_log);
        }
        ast_assert(0);
        /* stop here even if assert doesn't DO_CRASH */
        return -1;
    }
 
    /* last reference, destroy the object */
    if (obj->priv_data.destructor_fn != NULL) {
        obj->priv_data.destructor_fn(user_data);
    }
 
#ifdef AO2_DEBUG
    ast_atomic_fetchadd_int(&ao2.total_mem, - obj->priv_data.data_size);
    ast_atomic_fetchadd_int(&ao2.total_objects, -1);
#endif
 
    /* In case someone uses an object after it's been freed */
    obj->priv_data.magic = 0;
    /* Save the options locally so the ref_log print at the end doesn't access freed data */
    privdataoptions = obj->priv_data.options;
 
    switch (obj->priv_data.options & AO2_ALLOC_OPT_LOCK_MASK) {
    case AO2_ALLOC_OPT_LOCK_MUTEX:
        obj_mutex = INTERNAL_OBJ_MUTEX(user_data);
        lock_state = obj->priv_data.lockused ? "used" : "unused";
        ast_mutex_destroy(&obj_mutex->mutex.lock);
 
        ast_free(obj_mutex);
        break;
    case AO2_ALLOC_OPT_LOCK_RWLOCK:
        obj_rwlock = INTERNAL_OBJ_RWLOCK(user_data);
        lock_state = obj->priv_data.lockused ? "used" : "unused";
        ast_rwlock_destroy(&obj_rwlock->rwlock.lock);
 
        ast_free(obj_rwlock);
        break;
    case AO2_ALLOC_OPT_LOCK_NOLOCK:
        lock_state = "none";
        ast_free(obj);
        break;
    case AO2_ALLOC_OPT_LOCK_OBJ:
        obj_lockobj = INTERNAL_OBJ_LOCKOBJ(user_data);
        lock_state = obj->priv_data.lockused ? "used" : "unused";
        ao2_t_ref(obj_lockobj->lockobj.lock, -1, "release lockobj");
 
        ast_free(obj_lockobj);
        break;
    default:
        ast_log(__LOG_ERROR, file, line, func,
            "Invalid lock option on ao2 object %p\n", user_data);
        lock_state = "invalid";
        break;
    }
 
    if (ref_log && !(privdataoptions & AO2_ALLOC_OPT_NO_REF_DEBUG)) {
        fprintf(ref_log, "%p,%d,%d,%s,%d,%s,**destructor**lock-state:%s**,%s\n",
            user_data, delta, ast_get_tid(), file, line, func, lock_state, tag ?: "");
        fflush(ref_log);
    }
 
    return ret;
}

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

a	A 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.

{
    struct astobj2 *obj = __INTERNAL_OBJ_CHECK(user_data, file, line, func);
    struct astobj2_lock *obj_mutex;
    struct astobj2_rwlock *obj_rwlock;
    struct astobj2_lockobj *obj_lockobj;
    int res = 0;
 
    if (obj == NULL) {
        return -1;
    }
 
    if (ref_log) {
        obj->priv_data.lockused  = 1;
    }
 
    switch (obj->priv_data.options & AO2_ALLOC_OPT_LOCK_MASK) {
    case AO2_ALLOC_OPT_LOCK_MUTEX:
        obj_mutex = INTERNAL_OBJ_MUTEX(user_data);
        res = __ast_pthread_mutex_trylock(file, line, func, var, &obj_mutex->mutex.lock);
#ifdef AO2_DEBUG
        if (!res) {
            ast_atomic_fetchadd_int(&ao2.total_locked, 1);
        }
#endif
        break;
    case AO2_ALLOC_OPT_LOCK_RWLOCK:
        obj_rwlock = INTERNAL_OBJ_RWLOCK(user_data);
        switch (lock_how) {
        case AO2_LOCK_REQ_MUTEX:
        case AO2_LOCK_REQ_WRLOCK:
            res = __ast_rwlock_trywrlock(file, line, func, &obj_rwlock->rwlock.lock, var);
            if (!res) {
                ast_atomic_fetchadd_int(&obj_rwlock->rwlock.num_lockers, -1);
#ifdef AO2_DEBUG
                ast_atomic_fetchadd_int(&ao2.total_locked, 1);
#endif
            }
            break;
        case AO2_LOCK_REQ_RDLOCK:
            res = __ast_rwlock_tryrdlock(file, line, func, &obj_rwlock->rwlock.lock, var);
            if (!res) {
                ast_atomic_fetchadd_int(&obj_rwlock->rwlock.num_lockers, +1);
#ifdef AO2_DEBUG
                ast_atomic_fetchadd_int(&ao2.total_locked, 1);
#endif
            }
            break;
        }
        break;
    case AO2_ALLOC_OPT_LOCK_NOLOCK:
        /* The ao2 object has no lock. */
        return 0;
    case AO2_ALLOC_OPT_LOCK_OBJ:
        obj_lockobj = INTERNAL_OBJ_LOCKOBJ(user_data);
        res = __ao2_trylock(obj_lockobj->lockobj.lock, lock_how, file, func, line, var);
        break;
    default:
        ast_log(__LOG_ERROR, file, line, func, "Invalid lock option on ao2 object %p\n",
            user_data);
        return -1;
    }
 
    return res;
}

References __ao2_trylock(), __ast_pthread_mutex_trylock(), __ast_rwlock_tryrdlock(), __ast_rwlock_trywrlock(), __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, 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_trylock(), _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.

{
    if (!__is_ao2_object(user_data, file, line, func)) {
        /* Sanity checks. */
        return NULL;
    }
 
    flags &= ~OBJ_SEARCH_MASK;
    flags |= (OBJ_UNLINK | OBJ_SEARCH_OBJECT | OBJ_NODATA);
    __ao2_callback(c, flags, ao2_match_by_addr, user_data, tag, file, line, func);
 
    return NULL;
}

References __ao2_callback(), __is_ao2_object, ao2_match_by_addr(), c, NULL, OBJ_NODATA, 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

a	A 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.

{
    struct astobj2 *obj = __INTERNAL_OBJ_CHECK(user_data, file, line, func);
    struct astobj2_lock *obj_mutex;
    struct astobj2_rwlock *obj_rwlock;
    struct astobj2_lockobj *obj_lockobj;
    int res = 0;
    int current_value;
 
    if (obj == NULL) {
        return -1;
    }
 
    switch (obj->priv_data.options & AO2_ALLOC_OPT_LOCK_MASK) {
    case AO2_ALLOC_OPT_LOCK_MUTEX:
        obj_mutex = INTERNAL_OBJ_MUTEX(user_data);
        res = __ast_pthread_mutex_unlock(file, line, func, var, &obj_mutex->mutex.lock);
#ifdef AO2_DEBUG
        if (!res) {
            ast_atomic_fetchadd_int(&ao2.total_locked, -1);
        }
#endif
        break;
    case AO2_ALLOC_OPT_LOCK_RWLOCK:
        obj_rwlock = INTERNAL_OBJ_RWLOCK(user_data);
 
        current_value = ast_atomic_fetchadd_int(&obj_rwlock->rwlock.num_lockers, -1) - 1;
        if (current_value < 0) {
            /* It was a WRLOCK that we are unlocking.  Fix the count. */
            ast_atomic_fetchadd_int(&obj_rwlock->rwlock.num_lockers, -current_value);
        }
        res = __ast_rwlock_unlock(file, line, func, &obj_rwlock->rwlock.lock, var);
#ifdef AO2_DEBUG
        if (!res) {
            ast_atomic_fetchadd_int(&ao2.total_locked, -1);
        }
#endif
        break;
    case AO2_ALLOC_OPT_LOCK_NOLOCK:
        /* The ao2 object has no lock. */
        break;
    case AO2_ALLOC_OPT_LOCK_OBJ:
        obj_lockobj = INTERNAL_OBJ_LOCKOBJ(user_data);
        res = __ao2_unlock(obj_lockobj->lockobj.lock, file, func, line, var);
        break;
    default:
        ast_log(__LOG_ERROR, file, line, func, "Invalid lock option on ao2 object %p\n",
            user_data);
        res = -1;
        break;
    }
    return res;
}

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

{
    struct ao2_weakproxy *weakproxy;
 
    if (data_size < sizeof(*weakproxy)) {
        ast_assert(0);
        ast_log(LOG_ERROR, "Requested data_size smaller than minimum.\n");
        return NULL;
    }
 
    weakproxy = __ao2_alloc(data_size, destructor_fn, AO2_ALLOC_OPT_LOCK_MUTEX,
        tag, file, line, func);
 
    if (weakproxy) {
        struct astobj2 *weakproxy_internal;
 
        /* Just created weakproxy, no need to check if it's valid. */
        weakproxy_internal = INTERNAL_OBJ(weakproxy);
        weakproxy_internal->priv_data.magic = AO2_WEAK;
    }
 
    return weakproxy;
}

References __ao2_alloc(), AO2_ALLOC_OPT_LOCK_MUTEX, AO2_WEAK, ast_assert, ast_log, 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.

{
    void *proxy;
    void *obj = NULL;
    enum ao2_lock_req orig_lock;
 
    ast_assert(!!c);
    ast_assert(flags & OBJ_SEARCH_MASK);
    ast_assert(!(flags & ~(OBJ_SEARCH_MASK | OBJ_NOLOCK)));
 
    if (flags & OBJ_NOLOCK) {
        orig_lock = __adjust_lock(c, AO2_LOCK_REQ_RDLOCK, 1);
    } else {
        orig_lock = AO2_LOCK_REQ_RDLOCK;
        ao2_rdlock(c);
    }
 
    while ((proxy = ao2_find(c, arg, flags | OBJ_NOLOCK))) {
        obj = __ao2_weakproxy_get_object(proxy, 0, tag ?: __PRETTY_FUNCTION__, file, line, func);
 
        if (obj) {
            ao2_ref(proxy, -1);
            break;
        }
 
        /* Upgrade to a write lock */
        __adjust_lock(c, AO2_LOCK_REQ_WRLOCK, 1);
        ao2_unlink_flags(c, proxy, OBJ_NOLOCK);
        ao2_ref(proxy, -1);
    }
 
    if (flags & OBJ_NOLOCK) {
        /* We'll keep any upgraded lock */
        __adjust_lock(c, orig_lock, 1);
    } else {
        ao2_unlock(c);
    }
 
    return obj;
}

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

{
    struct astobj2 *internal = __INTERNAL_OBJ_CHECK(weakproxy, file, line, func);
    void *obj;
 
    if (!internal || internal->priv_data.magic != AO2_WEAK) {
        /* This method is meant to be run on weakproxy objects! */
        return NULL;
    }
 
    /* We have a weak object, grab reference to object within lock */
    if (!(flags & OBJ_NOLOCK)) {
        ao2_lock(weakproxy);
    }
 
    obj = internal->priv_data.weakptr;
    if (obj) {
        __ao2_ref(obj, +1, tag, file, line, func);
    }
 
    if (!(flags & OBJ_NOLOCK)) {
        ao2_unlock(weakproxy);
    }
 
    return obj;
}

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

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.

{
    struct astobj2 *internal = __INTERNAL_OBJ_CHECK(weakproxy, file, line, func);
    int ret = -1;
 
    if (!internal || internal->priv_data.magic != AO2_WEAK) {
        /* This method is meant to be run on weakproxy objects! */
        return -2;
    }
 
    /* We have a weak object, grab lock. */
    if (!(flags & OBJ_NOLOCK)) {
        ao2_lock(weakproxy);
    }
 
    if (internal->priv_data.weakptr) {
        ret = __ao2_ref(internal->priv_data.weakptr, delta, tag, file, line, func);
    }
 
    if (!(flags & OBJ_NOLOCK)) {
        ao2_unlock(weakproxy);
    }
 
    return ret;
}

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

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

{
    struct astobj2 *weakproxy_internal = __INTERNAL_OBJ_CHECK(weakproxy, file, line, func);
    struct astobj2 *obj_internal = __INTERNAL_OBJ_CHECK(obj, file, line, func);
    int ret = -1;
 
    if (!weakproxy_internal
        || weakproxy_internal->priv_data.magic != AO2_WEAK) {
        return -1;
    }
 
    if (!obj_internal
        || obj_internal->priv_data.weakptr
        || obj_internal->priv_data.magic != AO2_MAGIC) {
        return -1;
    }
 
    if (!(flags & OBJ_NOLOCK)) {
        ao2_lock(weakproxy);
    }
 
    if (!weakproxy_internal->priv_data.weakptr) {
        __ao2_ref(obj, +1, tag, file, line, func);
        __ao2_ref(weakproxy, +1, tag, file, line, func);
 
        weakproxy_internal->priv_data.weakptr = obj;
        obj_internal->priv_data.weakptr = weakproxy;
 
        ret = 0;
    }
 
    if (!(flags & OBJ_NOLOCK)) {
        ao2_unlock(weakproxy);
        /* It is possible for obj to be accessed now.  It's allowed
         * for weakproxy to already be in a container.  Another thread
         * could have been waiting for a lock on weakproxy to retrieve
         * the object.
         */
    }
 
    return ret;
}

References __ao2_ref(), __INTERNAL_OBJ_CHECK, ao2_lock, AO2_MAGIC, ao2_unlock, AO2_WEAK, __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

self	Container to check integrity.
flags	OBJ_NOLOCK if a lock is already held on the container.

Return values

0	on success.
-1	on error.

Definition at line 856 of file astobj2_container.c.

{
    int res = 0;
 
    if (!is_ao2_object(self) || !self->v_table) {
        /* Sanity checks. */
        ast_assert(0);
        return -1;
    }
#if defined(AO2_DEBUG)
    if (!self->v_table->integrity) {
        /* No integrity check available.  Assume container is ok. */
        return 0;
    }
 
    if (!(flags & OBJ_NOLOCK)) {
        ao2_rdlock(self);
    }
    res = self->v_table->integrity(self);
    if (!(flags & OBJ_NOLOCK)) {
        ao2_unlock(self);
    }
#endif  /* defined(AO2_DEBUG) */
    return res;
}

References ao2_rdlock, ao2_unlock, ast_assert, is_ao2_object, OBJ_NOLOCK, and ao2_container::v_table.

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.

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

References ast_atomic_fetchadd_int(), and c.

Referenced by action_confbridgekick(), action_confbridgelist(), action_confbridgelistrooms(), action_confbridgesetsinglevideosrc(), action_confbridgestartrecord(), action_confbridgestoprecord(), action_lock_unlock_helper(), action_mute_unmute_helper(), active_channels(), ami_show_aors(), ami_show_auths(), ami_show_contacts(), ami_show_endpoints(), ami_show_resource_lists(), ao2_iterator_count(), app_is_finished(), ari_conf_get_owc_for_app(), ast_ari_applications_list(), ast_bridge_transfer_attended(), ast_bridge_transfer_blind(), ast_cdr_generic_unregister(), ast_endpoint_snapshot_create(), ast_get_chan_applicationmap(), ast_get_namedgroups(), ast_merge_contexts_and_delete(), 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_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), ast_tone_zone_count(), astobj2_test_1_helper(), auth_observer(), bridges_scrape_cb(), calc_metric(), cc_cli_output_status(), cel_pre_apply_config(), channels_scrape_cb(), check_events(), check_expiration_thread(), cleanup(), cleanup_module(), cli_display_parking_lot(), cli_eprofile_show_all(), cli_fax_show_sessions(), cli_profile_show_all(), cli_show_modules(), cli_show_monitors(), cli_show_tasks(), cli_tn_show_all(), client_config_show_all(), common_identify(), control_command_count(), control_wait(), cpg_confchg_cb(), create_sound_blob(), create_unsolicited_mwi_subscriptions(), device_state_cb(), dial_state_process_bridge_enter(), do_timing(), endelm(), endpoints_scrape_cb(), exten_state_pub_data_alloc(), find_contact(), format_ami_aor_handler(), get_device_state_causing_channels(), global_loaded_observer(), grow(), handle_cli_sound_show(), handle_feature_show(), handle_manager_show_events(), handle_registrations(), handle_show_hint(), handle_show_hints(), insert_test_vector(), ip_identify_apply(), load_common(), locals_show(), 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(), outbound_websocket_validate_cb(), parking_lot_remove_if_unused(), pjsip_acf_dial_contacts_read(), presence_state_cb(), print_queue(), pthread_timer_open(), publisher_start(), queue_exec(), queue_function_mem_read(), queued_set_size(), queued_task_pushed(), register_aor_core(), registrar_validate_contacts(), send_unsolicited_mwi_notify(), should_send_event(), shrink(), single_state_process_bridge_enter(), sip_options_apply_aor_configuration(), sip_options_contact_add_task(), sip_options_contact_delete_task(), sip_options_unused_endpoint_state_compositor(), sla_in_use(), smdi_load(), sorcery_memory_cache_create(), sorcery_memory_cache_dump(), sorcery_memory_cache_populate(), 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(), system_create_resolver_and_set_nameservers(), test_ao2_iteration(), test_cel_peer_strings_match(), test_container_clone(), test_sub(), threadpool_send_state_changed(), tps_shutdown(), 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

self	Container to dump.
flags	OBJ_NOLOCK if a lock is already held on the container.
name	Container name. (NULL if anonymous)
where	User data needed by prnt to determine where to put output.
prnt	Print output callback function to use.
prnt_obj	Callback function to print the given object's key. (NULL if not available)

Definition at line 792 of file astobj2_container.c.

{
    if (!is_ao2_object(self) || !self->v_table) {
        prnt(where, "Invalid container\n");
        ast_assert(0);
        return;
    }
 
    if (!(flags & OBJ_NOLOCK)) {
        ao2_rdlock(self);
    }
    if (name) {
        prnt(where, "Container name: %s\n", name);
    }
#if defined(AO2_DEBUG)
    if (self->v_table->dump) {
        self->v_table->dump(self, where, prnt, prnt_obj);
    } else
#endif  /* defined(AO2_DEBUG) */
    {
        prnt(where, "Container dump not available.\n");
    }
    if (!(flags & OBJ_NOLOCK)) {
        ao2_unlock(self);
    }
}

References ao2_rdlock, ao2_unlock, ast_assert, is_ao2_object, name, OBJ_NOLOCK, and ao2_container::v_table.

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

dest	Container to copy src object references into.
src	Container to copy all object references from.
flags	OBJ_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

0	on success.
-1	on error.

Definition at line 673 of file astobj2_container.c.

{
    void *obj;
    int res = 0;
 
    if (!(flags & OBJ_NOLOCK)) {
        ao2_rdlock(src);
        ao2_wrlock(dest);
    }
    obj = ao2_callback(src, OBJ_NOLOCK, dup_obj_cb, dest);
    if (obj) {
        /* Failed to put this obj into the dest container. */
        ao2_t_ref(obj, -1, "Failed to put this object into the dest container.");
 
        /* Remove all items from the dest container. */
        ao2_callback(dest, OBJ_NOLOCK | OBJ_UNLINK | OBJ_NODATA | OBJ_MULTIPLE, NULL,
            NULL);
        res = -1;
    }
    if (!(flags & OBJ_NOLOCK)) {
        ao2_unlock(dest);
        ao2_unlock(src);
    }
 
    return res;
}

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_get_container(), cli_get_container(), cli_get_container(), cli_show_monitors(), cli_show_tasks(), cli_unid_get_container(), geoloc_config_list_locations(), geoloc_config_list_profiles(), geoloc_config_show_profiles(), handle_cli_sounds_show(), sip_options_apply_aor_configuration(), stasis_show_topics(), tps_report_taskprocessor_list(), and tps_shutdown().

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

dest	Container to copy src strong object references into.
src	Container to copy all weak object references from.
flags	OBJ_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

0	on success.
-1	on error.

Definition at line 726 of file astobj2_container.c.

{
    void *obj;
    int res = 0;
 
    if (!(flags & OBJ_NOLOCK)) {
        ao2_rdlock(src);
        ao2_wrlock(dest);
    }
    obj = ao2_callback(src, OBJ_NOLOCK, dup_weakproxy_cb, dest);
    if (obj) {
        /* Failed to put this obj into the dest container. */
        ao2_t_ref(obj, -1, "Failed to put this object into the dest container.");
 
        /* Remove all items from the dest container. */
        ao2_callback(dest, OBJ_NOLOCK | OBJ_UNLINK | OBJ_NODATA | OBJ_MULTIPLE, NULL,
            NULL);
        res = -1;
    }
    if (!(flags & OBJ_NOLOCK)) {
        ao2_unlock(dest);
        ao2_unlock(src);
    }
 
    return res;
}

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

name	Name to register the container under.
self	Container to register.
prnt_obj	Callback function to print the given object's key. (NULL if not available)

Return values

0	on success.
-1	on error.

Definition at line 958 of file astobj2_container.c.

{
    int res = 0;
#if defined(AO2_DEBUG)
    struct ao2_reg_container *reg;
 
    reg = ao2_t_alloc_options(sizeof(*reg) + strlen(name), ao2_reg_destructor,
        AO2_ALLOC_OPT_LOCK_NOLOCK, "Container registration object.");
    if (!reg) {
        return -1;
    }
 
    /* Fill in registered entry */
    ao2_t_ref(self, +1, "Registering container.");
    reg->registered = self;
    reg->prnt_obj = prnt_obj;
    strcpy(reg->name, name);/* safe */
 
    if (!ao2_t_link(reg_containers, reg, "Save registration object.")) {
        res = -1;
    }
 
    ao2_t_ref(reg, -1, "Done registering container.");
#endif  /* defined(AO2_DEBUG) */
    return res;
}

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

Referenced by ast_bridging_init(), ast_pbx_init(), get_instance(), load_module(), 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

self	Container to display statistics.
flags	OBJ_NOLOCK if a lock is already held on the container.
name	Container name. (NULL if anonymous)
where	User data needed by prnt to determine where to put output.
prnt	Print output callback function to use.

Definition at line 819 of file astobj2_container.c.

{
    if (!is_ao2_object(self) || !self->v_table) {
        prnt(where, "Invalid container\n");
        ast_assert(0);
        return;
    }
 
    if (!(flags & OBJ_NOLOCK)) {
        ao2_rdlock(self);
    }
    if (name) {
        prnt(where, "Container name: %s\n", name);
    }
    prnt(where, "Number of objects: %d\n", self->elements);
#if defined(AO2_DEBUG)
    prnt(where, "Number of nodes: %d\n", self->nodes);
    prnt(where, "Number of empty nodes: %d\n", self->nodes - self->elements);
    /*
     * XXX
     * If the max_empty_nodes count gets out of single digits you
     * likely have a code path where ao2_iterator_destroy() is not
     * called.
     *
     * Empty nodes do not harm the container but they do make
     * container operations less efficient.
     */
    prnt(where, "Maximum empty nodes: %d\n", self->max_empty_nodes);
    if (self->v_table->stats) {
        self->v_table->stats(self, where, prnt);
    }
#endif  /* defined(AO2_DEBUG) */
    if (!(flags & OBJ_NOLOCK)) {
        ao2_unlock(self);
    }
}

References ao2_rdlock, ao2_unlock, ast_assert, ao2_container::elements, is_ao2_object, name, OBJ_NOLOCK, and ao2_container::v_table.

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

name	Name the container is registered under.

Definition at line 985 of file astobj2_container.c.

{
#if defined(AO2_DEBUG)
    ao2_t_find(reg_containers, name, OBJ_UNLINK | OBJ_NODATA | OBJ_SEARCH_KEY,
        "Unregister container");
#endif  /* defined(AO2_DEBUG) */
}

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

Referenced by bridge_cleanup(), cdr_engine_shutdown(), close_instance(), load_module(), pbx_shutdown(), 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.

{
    if (iter) {
        ao2_iterator_destroy(iter);
    }
}

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

iter	the iterator to query

Returns

The number of objects in the iterated container

Definition at line 630 of file astobj2_container.c.

{
    return ao2_container_count(iter->c);
}

References ao2_container_count(), and ao2_iterator::c.

ao2_iterator_destroy()

void ao2_iterator_destroy

(

struct ao2_iterator *

iter

)

Destroy a container iterator.

Parameters

iter	the 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.

{
    /* Release any last container node reference. */
    ao2_iterator_restart(iter);
 
    /* Release the iterated container reference. */
    ao2_t_ref(iter->c, -1, "Unref iterator in ao2_iterator_destroy");
    iter->c = NULL;
 
    /* Free the malloced iterator. */
    if (iter->flags & AO2_ITERATOR_MALLOCD) {
        ast_free(iter);
    }
}

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

Referenced by __iax2_show_peers(), __manager_event_sessions_va(), __queues_show(), __test_cel_generate_peer_str(), aco_set_defaults(), action_agents(), action_confbridgelistrooms(), action_coreshowchannelmap(), action_coreshowchannels(), action_devicestatelist(), action_extensionstatelist(), action_meetmelist(), action_presencestatelist(), 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_conf_get_owc_for_app(), 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_channel_dialed_causes_find(), ast_channel_dialed_causes_find_multiple(), ast_complete_channels(), ast_endpoint_snapshot_create(), ast_format_cache_get_by_codec(), ast_merge_contexts_and_delete(), ast_msg_var_iterator_destroy(), ast_multi_channel_blob_get_channels(), ast_pickup_find_by_group(), ast_print_namedgroups(), ast_refer_var_iterator_destroy(), ast_sip_destroy_scheduler(), ast_sip_for_each_contact(), ast_sorcery_objectset_create2(), ast_sorcery_objectset_json_create(), ast_srtp_unprotect(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), ast_var_indications(), ast_var_indications_table(), astman_verify_session_readpermissions(), astman_verify_session_writepermissions(), astobj2_test_1_helper(), auth_observer(), authenticate(), authenticate_reply(), bridge_app_subscribed_involved(), bridge_channel_event_join_leave(), bridge_channel_moving(), bridge_channel_talking(), bridges_scrape_cb(), build_cli_notify(), calendar_query_exec(), cel_generate_peer_str(), channels_scrape_cb(), check_access(), check_events(), clear_queue(), clear_stats(), cli_complete_endpoint(), cli_complete_notify(), cli_complete_registration(), cli_complete_show(), cli_complete_uri(), cli_console_active(), cli_display_named_acl_list(), cli_fax_show_sessions(), cli_list_devices(), cli_show_channels(), cli_show_modules(), cli_show_monitors(), cli_show_tasks(), cli_tps_reset_stats_all(), compare_weight(), complete_app(), 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_queue_remove_member(), complete_session(), complete_show_sorcery_object(), complete_sorcery_object(), complete_user_profile_name(), complete_userno(), conf_queue_dtmf(), config_hook_exec(), config_object_tab_complete_name(), configure_parking_extensions(), container_to_json_array(), control_dispatch_all(), control_flush_queue(), control_prestart_dispatch_all(), coreshowchannelmap_add_connected_channels(), destroy_pvts(), device_state_cb(), device_state_cb(), device_state_notify_callbacks(), dial_state_process_bridge_enter(), dialgroup_read(), disable_marked_lots(), dump_queue_members(), endpoints_scrape_cb(), exten_state_publisher_state_cb(), extension_state_cb(), fax_session_tab_complete(), find_contact(), find_queue_by_name_rt(), find_ringing_channel(), find_session(), find_session_by_nonce(), free_members(), generate_or_link_lots_to_configs(), geoloc_config_list_locations(), geoloc_config_list_profiles(), geoloc_config_show_profiles(), get_device_state_causing_channels(), get_member_status(), get_transferee(), 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_classes(), handle_cli_moh_show_files(), handle_cli_moh_unregister_class(), handle_cli_odbc_show(), handle_cli_sound_show(), handle_cli_status(), handle_export_primitives(), handle_kickmanconn(), handle_manager_show_event(), handle_manager_show_events(), handle_show_calendar(), handle_show_calendars(), handle_show_hint(), handle_show_hints(), handle_show_named_acl_cmd(), handle_showmanconn(), handle_skel_show_games(), handle_skel_show_levels(), handle_voicemail_show_aliases(), hangupcause_read(), has_mwi_subscription(), iax2_getpeername(), iax2_getpeertrunk(), interface_exists(), ip_identify_apply(), is_longest_waiting_caller(), iterator_destroy(), 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(), locals_show(), manager_fax_sessions(), manager_iax2_show_peer_list(), manager_parking_status_all_lots(), manager_parking_status_single_lot(), manager_queues_status(), manager_queues_summary(), 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(), outbound_sessions_load(), outbound_websocket_validate_cb(), parking_lot_get_space(), pjsip_acf_dial_contacts_read(), pjsip_aor_function_read(), poke_all_peers(), pp_each_user_helper(), presence_state_cb(), presence_state_notify_callbacks(), print_queue(), prune_peers(), prune_users(), purge_sessions(), queue_function_mem_read(), queue_function_queuememberlist(), queue_mwi_event(), qupd_exec(), reload(), reload(), reload_single_queue(), remove_all_configured_parking_lot_extensions(), remove_pending_parking_lot_extensions(), rt_handle_member_record(), session_find_by_app(), set_member_paused(), set_member_value(), set_transfer_variables_all(), show_codecs(), single_state_process_bridge_enter(), sip_options_apply_aor_configuration(), sip_options_cleanup_task(), sip_options_endpoint_unlink_aor_feeders(), sip_options_get_endpoint_state_compositor_state(), sip_outbound_publish_synchronize(), sla_calc_station_delays(), sla_change_trunk_state(), sla_queue_event_conf(), sla_show_stations(), 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(), 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(), transport_state_do_reg_callbacks(), try_calling(), unbound_config_preapply(), update_queue(), update_realtime_members(), xmpp_pubsub_create_affiliations(), xmpp_show_buddies(), 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

c	the container
flags	one or more flags from ao2_iterator_flags.

Returns

the constructed iterator

Note

This function does not take a pointer to an iterator; rather, it returns an iterator structure that should be assigned to (overwriting) an existing iterator structure allocated on the stack or on the heap.

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

initialize an iterator so we start from the first object

Examples

app_skel.c.

Definition at line 485 of file astobj2_container.c.

{
    struct ao2_iterator a = {
        .c = c,
        .flags = flags
    };
 
    ao2_t_ref(c, +1, "Init iterator with container.");
 
    return a;
}

References a, ao2_t_ref, c, and ao2_iterator::flags.

Referenced by __iax2_show_peers(), __manager_event_sessions_va(), __queues_show(), __test_cel_generate_peer_str(), aco_set_defaults(), action_agents(), action_confbridgelistrooms(), action_coreshowchannelmap(), action_coreshowchannels(), action_devicestatelist(), action_extensionstatelist(), action_meetmelist(), action_presencestatelist(), 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_conf_get_owc_for_app(), 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_channel_dialed_causes_find(), ast_complete_channels(), ast_endpoint_snapshot_create(), ast_format_cache_get_by_codec(), ast_merge_contexts_and_delete(), ast_msg_var_iterator_init(), ast_pickup_find_by_group(), ast_print_namedgroups(), ast_refer_var_iterator_init(), ast_sip_destroy_scheduler(), ast_sip_for_each_contact(), ast_sorcery_objectset_create2(), ast_sorcery_objectset_json_create(), ast_srtp_unprotect(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), ast_tone_zone_iterator_init(), astman_verify_session_readpermissions(), astman_verify_session_writepermissions(), astobj2_test_1_helper(), auth_observer(), authenticate(), authenticate_reply(), bridge_app_subscribed_involved(), bridge_channel_event_join_leave(), bridge_channel_moving(), bridge_channel_talking(), bridges_scrape_cb(), build_cli_notify(), calendar_query_exec(), cel_generate_peer_str(), channels_scrape_cb(), check_access(), check_events(), clear_queue(), clear_stats(), cli_complete_endpoint(), cli_complete_notify(), cli_complete_registration(), cli_complete_show(), cli_complete_uri(), cli_console_active(), cli_display_named_acl_list(), cli_fax_show_sessions(), cli_list_devices(), cli_show_channels(), cli_show_modules(), cli_show_monitors(), cli_show_tasks(), cli_tps_reset_stats_all(), compare_weight(), complete_app(), 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_queue_remove_member(), complete_session(), complete_show_sorcery_object(), complete_sorcery_object(), complete_user_profile_name(), complete_userno(), conf_queue_dtmf(), config_hook_exec(), config_object_tab_complete_name(), configure_parking_extensions(), container_to_json_array(), control_dispatch_all(), control_flush_queue(), control_prestart_dispatch_all(), coreshowchannelmap_add_connected_channels(), destroy_pvts(), device_state_cb(), device_state_cb(), device_state_notify_callbacks(), dial_state_process_bridge_enter(), dialgroup_read(), disable_marked_lots(), dump_queue_members(), endpoints_scrape_cb(), exten_state_publisher_state_cb(), extension_state_cb(), fax_session_tab_complete(), find_contact(), find_queue_by_name_rt(), find_ringing_channel(), find_session(), find_session_by_nonce(), free_members(), generate_or_link_lots_to_configs(), geoloc_config_list_locations(), geoloc_config_list_profiles(), geoloc_config_show_profiles(), get_device_state_causing_channels(), get_member_status(), get_transferee(), 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_classes(), handle_cli_moh_show_files(), handle_cli_moh_unregister_class(), handle_cli_odbc_show(), handle_cli_sound_show(), handle_cli_status(), handle_export_primitives(), handle_kickmanconn(), handle_manager_show_event(), handle_show_calendar(), handle_show_calendars(), handle_show_hint(), handle_show_hints(), handle_show_named_acl_cmd(), 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(), is_longest_waiting_caller(), iterator_all_new(), jingle_add_google_candidates_to_transport(), jingle_add_ice_udp_candidates_to_transport(), jingle_request(), keepalive_transport_thread(), load_users(), local_devicestate(), locals_show(), manager_fax_sessions(), manager_iax2_show_peer_list(), manager_parking_status_all_lots(), manager_parking_status_single_lot(), manager_queues_status(), manager_queues_summary(), 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(), outbound_sessions_load(), outbound_websocket_validate_cb(), parking_lot_get_space(), pjsip_acf_dial_contacts_read(), pjsip_aor_function_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_queuememberlist(), qupd_exec(), reload(), reload(), reload_single_queue(), remove_all_configured_parking_lot_extensions(), remove_pending_parking_lot_extensions(), rt_handle_member_record(), session_find_by_app(), set_member_paused(), set_member_value(), set_transfer_variables_all(), show_codecs(), single_state_process_bridge_enter(), sip_options_apply_aor_configuration(), sip_options_cleanup_task(), sip_options_endpoint_unlink_aor_feeders(), sip_options_get_endpoint_state_compositor_state(), sip_outbound_publish_synchronize(), sla_calc_station_delays(), sla_change_trunk_state(), sla_queue_event_conf(), sla_show_stations(), 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(), stop_streams(), system_create_resolver_and_set_nameservers(), test_ao2_iteration(), test_container_clone(), topic_complete_name(), tps_report_taskprocessor_list(), tps_shutdown(), tps_taskprocessor_tab_complete(), try_calling(), unbound_config_preapply(), update_queue(), update_realtime_members(), xmpp_pubsub_create_affiliations(), xmpp_show_buddies(), and xmpp_show_clients().

ao2_iterator_restart()

void ao2_iterator_restart

(

struct ao2_iterator *

iter

)

Restart an iteration.

Parameters

iter	the 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.

{
    if (!is_ao2_object(iter->c)) {
        /* Sanity check. */
        return;
    }
 
    /* Release the last container node reference if we have one. */
    if (iter->last_node) {
        enum ao2_lock_req orig_lock;
 
        /*
         * Do a read lock in case the container node unref does not
         * destroy the node.  If the container node is destroyed then
         * the lock will be upgraded to a write lock.
         */
        if (iter->flags & AO2_ITERATOR_DONTLOCK) {
            orig_lock = __adjust_lock(iter->c, AO2_LOCK_REQ_RDLOCK, 1);
        } else {
            orig_lock = AO2_LOCK_REQ_MUTEX;
            ao2_rdlock(iter->c);
        }
 
        ao2_ref(iter->last_node, -1);
        iter->last_node = NULL;
 
        if (iter->flags & AO2_ITERATOR_DONTLOCK) {
            __adjust_lock(iter->c, orig_lock, 0);
        } else {
            ao2_unlock(iter->c);
        }
    }
 
    /* The iteration is no longer complete. */
    iter->complete = 0;
}

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.

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

References CMP_MATCH, and CMP_STOP.

Referenced by __ao2_unlink(), load_module(), 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]

obj

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

{
    struct astobj2 *obj;
    struct astobj2_lock *obj_mutex;
 
    obj = INTERNAL_OBJ_CHECK(user_data);
 
    if (obj == NULL) {
        return NULL;
    }
 
    switch (obj->priv_data.options & AO2_ALLOC_OPT_LOCK_MASK) {
    case AO2_ALLOC_OPT_LOCK_MUTEX:
        obj_mutex = INTERNAL_OBJ_MUTEX(user_data);
        return &obj_mutex->mutex.lock;
    default:
        break;
    }
 
    return NULL;
}

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(), consumer_wait_for_completion(), control_wait(), db_sync_thread(), pbx_outgoing_attempt(), rtp_deallocate_transport(), sip_session_suspend_task(), stasis_subscription_join(), transaction_wait(), and wait_for_stimulus().

ao2_options_get()

unsigned int ao2_options_get

(

void *

obj

)

Retrieve the ao2 options used to create the object.

Parameters

obj	pointer to the (user-defined part) of an object.

Returns

options from enum ao2_alloc_opts.

Definition at line 781 of file astobj2.c.

{
    struct astobj2 *orig_obj;
 
    orig_obj = INTERNAL_OBJ_CHECK(obj);
    if (!orig_obj) {
        return 0;
    }
    return orig_obj->priv_data.options;
}

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]

obj

A pointer to the ao2 object

Return values

0	The object is not an ao2 object or wasn't locked successfully
1	The object's reference count was incremented and was locked

Definition at line 780 of file astobj2.h.

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]

obj

A pointer to the ao2 object

Return values

0	The object is not an ao2 object or wasn't unlocked successfully
1	The object was unlocked and it's reference count was decremented

Definition at line 800 of file astobj2.h.

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

weakproxy	The weak object
cb	Procedure to call when no real object is associated
data	Passed to cb
flags	OBJ_NOLOCK to avoid locking weakproxy.

Return values

0	Success
-1	Failure

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.

{
    struct astobj2 *weakproxy_internal = INTERNAL_OBJ_CHECK(weakproxy);
    int ret = -1;
    int hasobj;
 
    if (!weakproxy_internal || weakproxy_internal->priv_data.magic != AO2_WEAK) {
        return -1;
    }
 
    if (!(flags & OBJ_NOLOCK)) {
        ao2_lock(weakproxy);
    }
 
    hasobj = weakproxy_internal->priv_data.weakptr != NULL;
    if (hasobj) {
        struct ao2_weakproxy *weak = weakproxy;
        struct ao2_weakproxy_notification *sub = ast_calloc(1, sizeof(*sub));
 
        if (sub) {
            sub->cb = cb;
            sub->data = data;
            AST_LIST_INSERT_HEAD(&weak->destroyed_cb, sub, list);
            ret = 0;
        }
    }
 
    if (!(flags & OBJ_NOLOCK)) {
        ao2_unlock(weakproxy);
    }
 
    if (!hasobj) {
        cb(weakproxy, data);
        ret = 0;
    }
 
    return ret;
}

References ao2_lock, ao2_unlock, AO2_WEAK, ast_calloc, AST_LIST_INSERT_HEAD, ao2_weakproxy_notification::cb, ao2_weakproxy_notification::data, stasis_subscription::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(), state_alloc(), and websocket_new().

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

weakproxy	The weak object
cb	Callback to remove from destroy notification list
data	Data pointer to match
flags	OBJ_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

0	cb / data pair not found, nothing removed.
-1	Failure 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.

{
    struct astobj2 *internal_weakproxy = INTERNAL_OBJ_CHECK(weakproxy);
    struct ao2_weakproxy *weak;
    struct ao2_weakproxy_notification *sub;
    int ret = 0;
 
    if (!internal_weakproxy || internal_weakproxy->priv_data.magic != AO2_WEAK || !destroyed_cb) {
        return -1;
    }
 
    if (!(flags & OBJ_NOLOCK)) {
        ao2_lock(weakproxy);
    }
 
    weak = weakproxy;
    AST_LIST_TRAVERSE_SAFE_BEGIN(&weak->destroyed_cb, sub, list) {
        if (sub->cb == destroyed_cb && sub->data == data) {
            AST_LIST_REMOVE_CURRENT(list);
            ast_free(sub);
            ret++;
            if (!(flags & OBJ_MULTIPLE)) {
                break;
            }
        }
    }
    AST_LIST_TRAVERSE_SAFE_END;
 
    if (!(flags & OBJ_NOLOCK)) {
        ao2_unlock(weakproxy);
    }
 
    return ret;
}

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, stasis_subscription::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().