[svn-commits] rmudgett: trunk r394846 - /trunk/include/asterisk/astobj2.h
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Fri Jul 19 20:11:41 CDT 2013
Author: rmudgett
Date: Fri Jul 19 20:11:38 2013
New Revision: 394846
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=394846
Log:
Regroup the ao2 search_flags.
Moved the OBJ_POINTER, OBJ_KEY, and OBJ_PARTIAL_KEY flags together into a
field and renamed them to OBJ_SEARCH_OBJECT, OBJ_SEARCH_KEY, and
OBJ_SEARCH_PARTIAL_KEY respectively. The values were selected to keep
existing code compiling and working until the codebase can be changed to
stop using these values as bit flags and use them as an enum field.
The old names are defined to the new names for backward compatibility.
Modified:
trunk/include/asterisk/astobj2.h
Modified: trunk/include/asterisk/astobj2.h
URL: http://svnview.digium.com/svn/asterisk/trunk/include/asterisk/astobj2.h?view=diff&rev=394846&r1=394845&r2=394846
==============================================================================
--- trunk/include/asterisk/astobj2.h (original)
+++ trunk/include/asterisk/astobj2.h Fri Jul 19 20:11:38 2013
@@ -770,12 +770,12 @@
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_POINTER - if set, 'arg' is an object pointer, and a hash table
+ 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_KEY - if set, 'arg', is a search key item that is not an object.
- Similar to OBJ_POINTER and mutually exclusive.
- OBJ_PARTIAL_KEY - if set, 'arg', is a partial search key item that is not an object.
- Similar to OBJ_KEY and mutually exclusive.
+ 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.
@@ -786,13 +786,13 @@
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_POINTER - if set, 'arg' is an object pointer, and a hash table
+ 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_KEY - if set, 'arg', is a search key item that is not an object.
- Similar to OBJ_POINTER and mutually exclusive.
- OBJ_PARTIAL_KEY - if set, 'arg', is a partial search key item that is not an object.
- Similar to OBJ_KEY and mutually exclusive.
+ 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
@@ -859,11 +859,6 @@
/*!
* \brief Flags passed to ao2_callback_fn(), ao2_hash_fn(), and ao2_sort_fn() to modify behaviour.
- *
- * \todo XXX OBJ_POINTER, OBJ_KEY, and OBJ_PARTIAL_KEY need to
- * be put into a bit field like OBJ_ORDER_MASK since they are
- * mutually exclusive. This change unfortunately is not
- * backwards compatible.
*/
enum search_flags {
/*!
@@ -881,6 +876,59 @@
* result of of the callback function has the CMP_STOP bit set.
*/
OBJ_MULTIPLE = (1 << 2),
+ /*!
+ * \brief Continue if a match is not found.
+ *
+ * \details
+ * This flag forces a whole container search. The
+ * OBJ_SEARCH_OBJECT, OBJ_SEARCH_KEY, and OBJ_SEARCH_PARTIAL_KEY
+ * flags just specify where to start the search in the
+ * container. If the search is not stopped early then the
+ * search _continues_ until the search wraps around to the
+ * starting point.
+ *
+ * Normal searches start where the search key specifies to start
+ * and end when the search key indicates that the object is not
+ * in the container.
+ *
+ * For hash containers, this tells the ao2_callback() core to
+ * keep searching through the rest of the buckets if a match is
+ * not found in the starting bucket defined by the hash value on
+ * the argument.
+ *
+ * For rbtree containers, if the search key is not in the
+ * container, the search will start either at the first item
+ * before the search key or the first item after the search key.
+ *
+ * \note The supplied ao2_callback_fn is called for every node
+ * in the container from the starting point.
+ */
+ OBJ_CONTINUE = (1 << 3),
+ /*!
+ * \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.
*
@@ -892,52 +940,8 @@
* \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.
- *
- * \note OBJ_POINTER, OBJ_KEY, and OBJ_PARTIAL_KEY are mutually
- * exclusive.
- */
- OBJ_POINTER = (1 << 3),
- /*!
- * \brief Continue if a match is not found.
- *
- * \details
- * This flag forces a whole container search. The OBJ_POINTER,
- * OBJ_KEY, and OBJ_PARTIAL_KEY flags just specify where to
- * start the search in the container. If the search is not
- * stopped early then the search _continues_ until the search
- * wraps around to the starting point.
- *
- * Normal searches start where the search key specifies to start
- * and end when the search key indicates that the object is not
- * in the container.
- *
- * For hash containers, this tells the ao2_callback() core to
- * keep searching through the rest of the buckets if a match is
- * not found in the starting bucket defined by the hash value on
- * the argument.
- *
- * For rbtree containers, if the search key is not in the
- * container, the search will start either at the first item
- * before the search key or the first item after the search key.
- *
- * \note The supplied ao2_callback_fn is called for every node
- * in the container from the starting point.
- */
- OBJ_CONTINUE = (1 << 4),
- /*!
- * \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 << 5),
+ */
+ OBJ_SEARCH_OBJECT = (1 << 5),
/*!
* \brief The arg parameter is a search key, but is not an object.
*
@@ -950,13 +954,10 @@
* \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.
- *
- * \note OBJ_POINTER, OBJ_KEY, and OBJ_PARTIAL_KEY are mutually
- * exclusive.
- */
- OBJ_KEY = (1 << 6),
- /*!
- * \brief The arg parameter is a partial search key similar to OBJ_KEY.
+ */
+ 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
@@ -968,11 +969,8 @@
* \note The supplied ao2_callback_fn is called after the
* container nodes have been filtered by the ao2_sort_fn
* function.
- *
- * \note OBJ_POINTER, OBJ_KEY, and OBJ_PARTIAL_KEY are mutually
- * exclusive.
- */
- OBJ_PARTIAL_KEY = (1 << 7),
+ */
+ OBJ_SEARCH_PARTIAL_KEY = (4 << 5),
/*! \brief Traverse order option field mask. */
OBJ_ORDER_MASK = (0x03 << 8),
@@ -1000,6 +998,16 @@
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.
*
@@ -1065,9 +1073,9 @@
* \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_POINTER - if set, 'arg', is an object.
- * OBJ_KEY - if set, 'arg', is a search key item that is not an object.
- * OBJ_PARTIAL_KEY - if set, 'arg', is a partial search key item that is not an object.
+ * 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.
@@ -1083,9 +1091,9 @@
* \param arg callback argument from ao2_callback()
* \param data arbitrary data from ao2_callback()
* \param flags flags from ao2_callback()
- * OBJ_POINTER - if set, 'arg', is an object.
- * OBJ_KEY - if set, 'arg', is a search key item that is not an object.
- * OBJ_PARTIAL_KEY - if set, 'arg', is a partial search key item that is not an object.
+ * 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.
@@ -1097,8 +1105,8 @@
*
* \param obj pointer to the (user-defined part) of an object.
* \param flags flags from ao2_callback()
- * OBJ_POINTER - if set, 'obj', is an object.
- * OBJ_KEY - if set, 'obj', is a search key item that is not an object.
+ * 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.
*
* \return Computed hash value.
*/
@@ -1110,9 +1118,9 @@
* \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_POINTER - if set, 'obj_right', is an object.
- * OBJ_KEY - if set, 'obj_right', is a search key item that is not an object.
- * OBJ_PARTIAL_KEY - if set, 'obj_right', is a partial search key item that is not an object.
+ * 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.
*
* \retval <0 if obj_left < obj_right
* \retval =0 if obj_left == obj_right
@@ -1574,10 +1582,12 @@
* - 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
+ * 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_POINTER is set, the traversed items will be restricted
+ * - 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
@@ -1634,9 +1644,9 @@
* functions such as find() do
* OBJ_MULTIPLE return multiple matches
* Default is no.
- * OBJ_POINTER the pointer is an object pointer
- * OBJ_KEY the pointer is to a search key
- * OBJ_PARTIAL_KEY the pointer is to a partial search key
+ * 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.
@@ -1673,9 +1683,9 @@
* allows the caller to pass in arbitrary data.
*
* This call would be used instead of ao2_callback() when the caller needs to pass
- * OBJ_POINTER as part of the flags argument (which in turn requires passing in a
- * prototype ao2 object for 'arg') and also needs access to other non-global data
- * to complete it's comparison or task.
+ * 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.
*
More information about the svn-commits
mailing list