[asterisk-commits] russell: trunk r155244 - /trunk/include/asterisk/astobj2.h

[SVN commits to the Asterisk project]

Author: russell
Date: Fri Nov  7 09:01:02 2008
New Revision: 155244

URL: http://svn.digium.com/view/asterisk?view=rev&rev=155244
Log:
Clarify which part of OBJ_MULTIPLE is not implemented, and under what case it
is perfectly fine to use.  (Inspired by a question I received about my last
commit.)

Modified:
    trunk/include/asterisk/astobj2.h

Modified: trunk/include/asterisk/astobj2.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/astobj2.h?view=diff&rev=155244&r1=155243&r2=155244
==============================================================================
--- trunk/include/asterisk/astobj2.h (original)
+++ trunk/include/asterisk/astobj2.h Fri Nov  7 09:01:02 2008
@@ -511,7 +511,7 @@
     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_MULTIPLE - don't stop at first match (not fully implemented)
 	OBJ_POINTER	- if set, 'arg' is an object pointer, and a hashtable
                   search will be done. If not, a traversal is done.
 
@@ -523,7 +523,7 @@
       - 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_MULTIPLE - don't stop at first match (not fully 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'..
@@ -615,7 +615,10 @@
 	 *  its refcount. */
 	OBJ_NODATA	 = (1 << 1),
 	/*! Don't stop at the first match in ao2_callback()
-	 *  \note This is not fully implemented. */
+	 *  \note This is not fully implemented.   Using OBJ_MULTIME with OBJ_NODATA
+	 *  is perfectly fine.  The part that is not implemented is the case where
+	 *  multiple objects should be returned by ao2_callback().
+	 */
 	OBJ_MULTIPLE = (1 << 2),
 	/*! obj is an object of the same type as the one being searched for,
 	 *  so use the object's hash function for optimized searching.