[asterisk-commits] murf: branch murf/bug11210 r90796 - /team/murf/bug11210/include/asterisk/
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Mon Dec 3 22:36:38 CST 2007
Author: murf
Date: Mon Dec 3 22:36:38 2007
New Revision: 90796
URL: http://svn.digium.com/view/asterisk?view=rev&rev=90796
Log:
Some enhancements to the explanations in astobj2.h. This is the kind of info I wish was there. Probably redundant, but...
Modified:
team/murf/bug11210/include/asterisk/astobj2.h
Modified: team/murf/bug11210/include/asterisk/astobj2.h
URL: http://svn.digium.com/view/asterisk/team/murf/bug11210/include/asterisk/astobj2.h?view=diff&rev=90796&r1=90795&r2=90796
==============================================================================
--- team/murf/bug11210/include/asterisk/astobj2.h (original)
+++ team/murf/bug11210/include/asterisk/astobj2.h Mon Dec 3 22:36:38 2007
@@ -65,10 +65,7 @@
ao2_ref(o, -1)
causing the destructor to be called (and then memory freed) when
- the refcount goes to 0. This is also available as ao2_unref(o),
- and returns NULL as a convenience, so you can do things like
- o = ao2_unref(o);
- and clean the original pointer to prevent errors.
+ the refcount goes to 0.
- ao2_ref(o, +1) can be used to modify the refcount on the
object in case we want to pass it around.
@@ -118,6 +115,8 @@
The function returns NULL in case of errors (and the object
is not inserted in the container). Other values mean success
(we are not supposed to use the value as a pointer to anything).
+Linking an object to a container increases its refcount by 1
+automatically.
\note While an object o is in a container, we expect that
my_hash_fn(o) will always return the same value. The function
@@ -211,17 +210,44 @@
c = ao2_container_alloc(size, cmp_fn, hash_fn)
allocate a container with desired size and default compare
and hash function
+ -The compare function returns an int, which
+ can be 0 for not found, CMP_STOP to stop end a traversal,
+ or CMP_MATCH if they are equal
+ -The hash function returns an int. The hash function
+ takes two argument, the object pointer and a flags field,
ao2_find(c, arg, flags)
returns zero or more element matching a given criteria
- (specified as arg). Flags indicate how many results we
- want (only one or all matching entries), and whether we
- should unlink the object from the container.
+ (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 (not implemented)
+ OBJ_POINTER - if set, 'arg' is an object pointer, and a hashtable
+ search will be done. If not, a traversal is done.
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 (not implemented)
+ OBJ_POINTER - if set, 'arg' is an object pointer, and a hashtable
+ search will be done. If not, a traversal is done through
+ all the hashtable 'buckets'..
+ - 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 noone else can change its content while we work on it.
However, we pay this with the fact that doing
@@ -378,7 +404,8 @@
* be called.
*
* \note If the object gets unlinked from the container, the container's
- * reference to the object will be automatically released.
+ * reference to the object will be automatically released. (The
+ * refcount will be decremented).
*/
void *ao2_unlink(struct ao2_container *c, void *obj);
@@ -393,10 +420,30 @@
* in a container, as described below.
*
* \param c A pointer to the container to operate on.
- * \param arg passed to the callback.
* \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 each object for which CMP_MATCH was set will be incremented,
+ and you will have no way of knowing which those are, until
+ the multiple-object-return functionality is implemented.
+ - If OBJ_POINTER 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. It's 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.
* \return A pointer to the object found/marked,
* a pointer to a list of objects matching comparison function,
* NULL if not found.
More information about the asterisk-commits
mailing list