kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2025-11-18 07:48:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix ao2obj.h comment typos and add missing link/unlink nolock debug defines.

Browse Source 
........

Merged revisions 342183 from http://svn.asterisk.org/svn/asterisk/branches/10


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@342184 65c4cc65-6c06-0410-ace0-fbb531ad65f3
This commit is contained in:
Richard Mudgett
2011-10-24 22:37:58 +00:00
parent f6cd5af36b
commit 41ade83749
1 changed files with 32 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
include/asterisk/astobj2.h
View File

@@ -46,7 +46,7 @@ As an additional feature, ao2 objects are associated to individual
locks. locks.
Creating an object requires the size of the object and Creating an object requires the size of the object and
and a pointer to the destructor function: a pointer to the destructor function:
struct foo *o; struct foo *o;
@@ -127,7 +127,7 @@ my_hash_fn(o) will always return the same value. The function
does not lock the object to be computed, so modifications of does not lock the object to be computed, so modifications of
those fields that affect the computation of the hash should those fields that affect the computation of the hash should
be done by extracting the object from the container, and be done by extracting the object from the container, and
reinserting it after the change (this is not terribly expensive). re-inserting it after the change (this is not terribly expensive).
\note A container with a single buckets is effectively a linked \note A container with a single buckets is effectively a linked
list. However there is no ordering among elements. list. However there is no ordering among elements.
@@ -142,12 +142,12 @@ list. However there is no ordering among elements.
An interface to help debug refcounting is provided An interface to help debug refcounting is provided
in this package. It is dependent on the REF_DEBUG macro being in this package. It is dependent on the REF_DEBUG macro being
defined in a source file, before the #include of astobj2.h, defined in a source file, before the #include of astobj2.h,
and in using variants of the normal ao2_xxxx functions and in using variants of the normal ao2_xxx functions
that are named ao2_t_xxxx instead, with an extra argument, a string, that are named ao2_t_xxx instead, with an extra argument, a string,
that will be printed out into /tmp/refs when the refcount for an that will be printed out into /tmp/refs when the refcount for an
object is changed. object is changed.
these ao2_t_xxxx variants are provided: these ao2_t_xxx variants are provided:
ao2_t_alloc(arg1, arg2, arg3) ao2_t_alloc(arg1, arg2, arg3)
ao2_t_ref(arg1,arg2,arg3) ao2_t_ref(arg1,arg2,arg3)
@@ -159,7 +159,7 @@ ao2_t_find(arg1,arg2,arg3,arg4)
ao2_t_iterator_next(arg1, arg2) ao2_t_iterator_next(arg1, arg2)
If you study each argument list, you will see that these functions all have If you study each argument list, you will see that these functions all have
one extra argument that their ao2_xxx counterpart. The last argument in one extra argument than their ao2_xxx counterpart. The last argument in
each case is supposed to be a string pointer, a "tag", that should contain each case is supposed to be a string pointer, a "tag", that should contain
enough of an explanation, that you can pair operations that increment the enough of an explanation, that you can pair operations that increment the
ref count, with operations that are meant to decrement the refcount. ref count, with operations that are meant to decrement the refcount.
@@ -194,7 +194,7 @@ The second column reflects how the operation affected the ref count
The remainder of the line specifies where in the file the call was made, The remainder of the line specifies where in the file the call was made,
and the function name, and the tag supplied in the function call. and the function name, and the tag supplied in the function call.
The **call destructor** is specified when the the destroy routine is The **call destructor** is specified when the destroy routine is
run for an object. It does not affect the ref count, but is important run for an object. It does not affect the ref count, but is important
in debugging, because it is possible to have the astobj2 system run it in debugging, because it is possible to have the astobj2 system run it
multiple times on the same object, commonly fatal to asterisk. multiple times on the same object, commonly fatal to asterisk.
@@ -538,7 +538,7 @@ Operations on container include:
OBJ_UNLINK - to remove the object, once found, from the container. 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_NODATA - don't return the object if found (no ref count change)
OBJ_MULTIPLE - don't stop at first match OBJ_MULTIPLE - don't stop at first match
OBJ_POINTER - if set, 'arg' is an object pointer, and a hashtable OBJ_POINTER - if set, 'arg' is an object pointer, and a hash table
search will be done. If not, a traversal is done. search will be done. If not, a traversal is done.
- \b ao2_callback(c, flags, fn, arg) - \b ao2_callback(c, flags, fn, arg)
@@ -550,9 +550,9 @@ Operations on container include:
OBJ_UNLINK - to remove the object, once found, from the container. 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_NODATA - don't return the object if found (no ref count change)
OBJ_MULTIPLE - don't stop at first match OBJ_MULTIPLE - don't stop at first match
OBJ_POINTER - if set, 'arg' is an object pointer, and a hashtable OBJ_POINTER - if set, 'arg' is an object pointer, and a hash table
search will be done. If not, a traversal is done through search will be done. If not, a traversal is done through
all the hashtable 'buckets'.. all the hash table 'buckets'..
- fn is a func that returns int, and takes 3 args: - fn is a func that returns int, and takes 3 args:
(void *obj, void *arg, int flags); (void *obj, void *arg, int flags);
obj is an object obj is an object
@@ -564,7 +564,7 @@ Operations on container include:
CMP_MATCH: This object is matched. CMP_MATCH: This object is matched.
Note that the entire operation is run with the container Note that the entire operation is run with the container
locked, so noone else can change its content while we work on it. locked, so nobody else can change its content while we work on it.
However, we pay this with the fact that doing However, we pay this with the fact that doing
anything blocking in the callback keeps the container anything blocking in the callback keeps the container
blocked. blocked.
@@ -714,9 +714,8 @@ struct ao2_container;
* *
* \param arg1 Number of buckets for hash * \param arg1 Number of buckets for hash
* \param arg2 Pointer to a function computing a hash value. * \param arg2 Pointer to a function computing a hash value.
* \param arg3 Pointer to a function comparating key-value * \param arg3 Pointer to a compare function used by ao2_find. (NULL to match everything)
* with a string. (can be NULL) * \param arg4 used for debugging.
* \param arg4
* *
* \return A pointer to a struct container. * \return A pointer to a struct container.
* *
@@ -767,7 +766,7 @@ int ao2_container_count(struct ao2_container *c);
* *
* \param arg1 the container to operate on. * \param arg1 the container to operate on.
* \param arg2 the object to be added. * \param arg2 the object to be added.
* \param arg3 used for debuging. * \param arg3 used for debugging.
* *
* \retval NULL on errors. * \retval NULL on errors.
* \retval newobj on success. * \retval newobj on success.
@@ -781,15 +780,17 @@ int ao2_container_count(struct ao2_container *c);
*/ */
#ifdef REF_DEBUG #ifdef REF_DEBUG
#define ao2_t_link(arg1, arg2, arg3) __ao2_link_debug((arg1), (arg2), 0, (arg3), __FILE__, __LINE__, __PRETTY_FUNCTION__) #define ao2_t_link(arg1, arg2, arg3) __ao2_link_debug((arg1), (arg2), 0, (arg3), __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_link(arg1, arg2) __ao2_link_debug((arg1), (arg2), 0, "", __FILE__, __LINE__, __PRETTY_FUNCTION__) #define ao2_link(arg1, arg2) __ao2_link_debug((arg1), (arg2), 0, "", __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_link_nolock(arg1, arg2) __ao2_link_debug((arg1), (arg2), OBJ_NOLOCK, "", __FILE__, __LINE__, __PRETTY_FUNCTION__) #define ao2_t_link_nolock(arg1, arg2, arg3) __ao2_link_debug((arg1), (arg2), OBJ_NOLOCK, (arg3), __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_link_nolock(arg1, arg2) __ao2_link_debug((arg1), (arg2), OBJ_NOLOCK, "", __FILE__, __LINE__, __PRETTY_FUNCTION__)
#else #else
#define ao2_t_link(arg1, arg2, arg3) __ao2_link((arg1), (arg2), 0) #define ao2_t_link(arg1, arg2, arg3) __ao2_link((arg1), (arg2), 0)
#define ao2_link(arg1, arg2) __ao2_link((arg1), (arg2), 0) #define ao2_link(arg1, arg2) __ao2_link((arg1), (arg2), 0)
#define ao2_link_nolock(arg1, arg2) __ao2_link((arg1), (arg2), OBJ_NOLOCK) #define ao2_t_link_nolock(arg1, arg2, arg3) __ao2_link((arg1), (arg2), OBJ_NOLOCK)
#define ao2_link_nolock(arg1, arg2) __ao2_link((arg1), (arg2), OBJ_NOLOCK)
#endif #endif
@@ -815,15 +816,17 @@ void *__ao2_link(struct ao2_container *c, void *newobj, int flags);
*/ */
#ifdef REF_DEBUG #ifdef REF_DEBUG
#define ao2_t_unlink(arg1, arg2, arg3) __ao2_unlink_debug((arg1), (arg2), 0, (arg3), __FILE__, __LINE__, __PRETTY_FUNCTION__) #define ao2_t_unlink(arg1, arg2, arg3) __ao2_unlink_debug((arg1), (arg2), 0, (arg3), __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_unlink(arg1, arg2) __ao2_unlink_debug((arg1), (arg2), 0, "", __FILE__, __LINE__, __PRETTY_FUNCTION__) #define ao2_unlink(arg1, arg2) __ao2_unlink_debug((arg1), (arg2), 0, "", __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_unlink_nolock(arg1, arg2) __ao2_unlink_debug((arg1), (arg2), OBJ_NOLOCK, "", __FILE__, __LINE__, __PRETTY_FUNCTION__) #define ao2_t_unlink_nolock(arg1, arg2, arg3) __ao2_unlink_debug((arg1), (arg2), OBJ_NOLOCK, (arg3), __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_unlink_nolock(arg1, arg2) __ao2_unlink_debug((arg1), (arg2), OBJ_NOLOCK, "", __FILE__, __LINE__, __PRETTY_FUNCTION__)
#else #else
#define ao2_t_unlink(arg1, arg2, arg3) __ao2_unlink((arg1), (arg2), 0) #define ao2_t_unlink(arg1, arg2, arg3) __ao2_unlink((arg1), (arg2), 0)
#define ao2_unlink(arg1, arg2) __ao2_unlink((arg1), (arg2), 0) #define ao2_unlink(arg1, arg2) __ao2_unlink((arg1), (arg2), 0)
#define ao2_unlink_nolock(arg1, arg2) __ao2_unlink((arg1), (arg2), OBJ_NOLOCK) #define ao2_t_unlink_nolock(arg1, arg2, arg3) __ao2_unlink((arg1), (arg2), OBJ_NOLOCK)
#define ao2_unlink_nolock(arg1, arg2) __ao2_unlink((arg1), (arg2), OBJ_NOLOCK)
#endif #endif
@@ -862,7 +865,7 @@ void *__ao2_unlink(struct ao2_container *c, void *obj, int flags);
flags is the same as flags passed into ao2_callback (flags are flags is the same as flags passed into ao2_callback (flags are
also used by ao2_callback). also used by ao2_callback).
* \param arg passed to the callback. * \param arg passed to the callback.
* \param tag used for debuging. * \param tag used for debugging.
* \return when OBJ_MULTIPLE is not included in the flags parameter, * \return when OBJ_MULTIPLE is not included in the flags parameter,
* the return value will be either the object found or NULL if no * the return value will be either the object found or NULL if no
* no matching object was found. if OBJ_MULTIPLE is included, * no matching object was found. if OBJ_MULTIPLE is included,
@@ -890,7 +893,7 @@ void *__ao2_unlink(struct ao2_container *c, void *obj, int flags);
* The p pointer can be a pointer to an object or to a key, * The p pointer can be a pointer to an object or to a key,
* we can say this looking at flags value. * we can say this looking at flags value.
* If p points to an object we will search for the object pointed * If p points to an object we will search for the object pointed
* by this value, otherwise we serch for a key value. * by this value, otherwise we search for a key value.
* If the key is not unique we only find the first matching valued. * If the key is not unique we only find the first matching valued.
* *
* The use of flags argument is the follow: * The use of flags argument is the follow: