Asterisk
/
asterisk
mirror of https://github.com/asterisk/asterisk
1
0
Fork 0
Code Issues Releases Wiki Activity

Regroup the ao2 search_flags.

Browse Source 
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.


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@394846 65c4cc65-6c06-0410-ace0-fbb531ad65f3
changes/78/78/1
Richard Mudgett 12 years ago
parent 643fb1ed14
commit 4e15046cf6
1 changed files with 77 additions and 67 deletions
Show Stats Download Patch File Download Diff File

144
include/asterisk/astobj2.h
Unescape View File

@ -770,12 +770,12 @@ 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 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. 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. OBJ_SEARCH_KEY - if set, 'arg', is a search key item that is not an object.
Similar to OBJ_POINTER and mutually exclusive. Similar to OBJ_SEARCH_OBJECT and mutually exclusive.
OBJ_PARTIAL_KEY - if set, 'arg', is a partial 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.
Similar to OBJ_KEY and mutually exclusive. Similar to OBJ_SEARCH_KEY and mutually exclusive.
- \b ao2_callback(c, flags, fn, arg) - \b ao2_callback(c, flags, fn, arg)
apply fn(obj, arg) to all objects in the container. apply fn(obj, arg) to all objects in the container.
@ -786,13 +786,13 @@ 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 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 search will be done. If not, a traversal is done through
all the hash table 'buckets'.. all the hash table 'buckets'..
OBJ_KEY - if set, 'arg', is a search key item that is not an object. OBJ_SEARCH_KEY - if set, 'arg', is a search key item that is not an object.
Similar to OBJ_POINTER and mutually exclusive. Similar to OBJ_SEARCH_OBJECT and mutually exclusive.
OBJ_PARTIAL_KEY - if set, 'arg', is a partial 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.
Similar to OBJ_KEY and mutually exclusive. Similar to OBJ_SEARCH_KEY and mutually exclusive.
- 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
@ -859,11 +859,6 @@ enum _cb_results {
/*! /*!
* \brief Flags passed to ao2_callback_fn(), ao2_hash_fn(), and ao2_sort_fn() to modify behaviour. * \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 { enum search_flags {
/*! /*!
@ -881,31 +876,16 @@ enum search_flags {
* result of of the callback function has the CMP_STOP bit set. * result of of the callback function has the CMP_STOP bit set.
*/ */
OBJ_MULTIPLE = (1 << 2), OBJ_MULTIPLE = (1 << 2),
/*!
* \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.
*
* \note OBJ_POINTER, OBJ_KEY, and OBJ_PARTIAL_KEY are mutually
* exclusive.
*/
OBJ_POINTER = (1 << 3),
/*! /*!
* \brief Continue if a match is not found. * \brief Continue if a match is not found.
* *
* \details * \details
* This flag forces a whole container search. The OBJ_POINTER, * This flag forces a whole container search. The
* OBJ_KEY, and OBJ_PARTIAL_KEY flags just specify where to * OBJ_SEARCH_OBJECT, OBJ_SEARCH_KEY, and OBJ_SEARCH_PARTIAL_KEY
* start the search in the container. If the search is not * flags just specify where to start the search in the
* stopped early then the search _continues_ until the search * container. If the search is not stopped early then the
* wraps around to the starting point. * search _continues_ until the search wraps around to the
* starting point.
* *
* Normal searches start where the search key specifies to start * Normal searches start where the search key specifies to start
* and end when the search key indicates that the object is not * and end when the search key indicates that the object is not
@ -923,7 +903,7 @@ enum search_flags {
* \note The supplied ao2_callback_fn is called for every node * \note The supplied ao2_callback_fn is called for every node
* in the container from the starting point. * in the container from the starting point.
*/ */
OBJ_CONTINUE = (1 << 4), OBJ_CONTINUE = (1 << 3),
/*! /*!
* \brief Assume that the ao2_container is already locked. * \brief Assume that the ao2_container is already locked.
* *
@ -937,7 +917,31 @@ enum search_flags {
* \note Only use this flag if the ao2_container is manually * \note Only use this flag if the ao2_container is manually
* locked already. * locked already.
*/ */
OBJ_NOLOCK = (1 << 5), 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. * \brief The arg parameter is a search key, but is not an object.
* *
@ -950,13 +954,10 @@ enum search_flags {
* \note The supplied ao2_callback_fn is called after the * \note The supplied ao2_callback_fn is called after the
* container nodes have been filtered by the ao2_hash_fn and/or * container nodes have been filtered by the ao2_hash_fn and/or
* ao2_sort_fn functions. * ao2_sort_fn functions.
*
* \note OBJ_POINTER, OBJ_KEY, and OBJ_PARTIAL_KEY are mutually
* exclusive.
*/ */
OBJ_KEY = (1 << 6), OBJ_SEARCH_KEY = (2 << 5),
/*! /*!
* \brief The arg parameter is a partial search key similar to OBJ_KEY. * \brief The arg parameter is a partial search key similar to OBJ_SEARCH_KEY.
* *
* \details * \details
* The partial key can be used by the ao2_sort_fn to guide the * The partial key can be used by the ao2_sort_fn to guide the
@ -968,11 +969,8 @@ enum search_flags {
* \note The supplied ao2_callback_fn is called after the * \note The supplied ao2_callback_fn is called after the
* container nodes have been filtered by the ao2_sort_fn * container nodes have been filtered by the ao2_sort_fn
* function. * 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. */ /*! \brief Traverse order option field mask. */
OBJ_ORDER_MASK = (0x03 << 8), OBJ_ORDER_MASK = (0x03 << 8),
@ -1000,6 +998,16 @@ enum search_flags {
OBJ_ORDER_POST = (3 << 8), 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. * \brief Options available when allocating an ao2 container object.
* *
@ -1065,9 +1073,9 @@ enum ao2_container_opts {
* \param obj pointer to the (user-defined part) of an object. * \param obj pointer to the (user-defined part) of an object.
* \param arg callback argument from ao2_callback() * \param arg callback argument from ao2_callback()
* \param flags flags from ao2_callback() * \param flags flags from ao2_callback()
* OBJ_POINTER - if set, 'arg', is an object. * OBJ_SEARCH_OBJECT - if set, 'arg', is an object.
* OBJ_KEY - if set, 'arg', is a search key item that is not an object. * OBJ_SEARCH_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_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. * The return values are a combination of enum _cb_results.
* Callback functions are used to search or manipulate objects in a container. * Callback functions are used to search or manipulate objects in a container.
@ -1083,9 +1091,9 @@ int ao2_match_by_addr(void *obj, void *arg, int flags);
* \param arg callback argument from ao2_callback() * \param arg callback argument from ao2_callback()
* \param data arbitrary data from ao2_callback() * \param data arbitrary data from ao2_callback()
* \param flags flags from ao2_callback() * \param flags flags from ao2_callback()
* OBJ_POINTER - if set, 'arg', is an object. * OBJ_SEARCH_OBJECT - if set, 'arg', is an object.
* OBJ_KEY - if set, 'arg', is a search key item that is not an object. * OBJ_SEARCH_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_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. * The return values are a combination of enum _cb_results.
* Callback functions are used to search or manipulate objects in a container. * Callback functions are used to search or manipulate objects in a container.
@ -1097,8 +1105,8 @@ typedef int (ao2_callback_data_fn)(void *obj, void *arg, void *data, int flags);
* *
* \param obj pointer to the (user-defined part) of an object. * \param obj pointer to the (user-defined part) of an object.
* \param flags flags from ao2_callback() * \param flags flags from ao2_callback()
* OBJ_POINTER - if set, 'obj', is an object. * OBJ_SEARCH_OBJECT - if set, 'obj', is an object.
* OBJ_KEY - if set, 'obj', is a search key item that is not an object. * OBJ_SEARCH_KEY - if set, 'obj', is a search key item that is not an object.
* *
* \return Computed hash value. * \return Computed hash value.
*/ */
@ -1110,9 +1118,9 @@ typedef int (ao2_hash_fn)(const void *obj, int flags);
* \param obj_left pointer to the (user-defined part) of an object. * \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 obj_right pointer to the (user-defined part) of an object.
* \param flags flags from ao2_callback() * \param flags flags from ao2_callback()
* OBJ_POINTER - if set, 'obj_right', is an object. * OBJ_SEARCH_OBJECT - if set, 'obj_right', is an object.
* OBJ_KEY - if set, 'obj_right', is a search key item that is not an object. * OBJ_SEARCH_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_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
* \retval =0 if obj_left == obj_right * \retval =0 if obj_left == obj_right
@ -1574,10 +1582,12 @@ void *__ao2_unlink(struct ao2_container *c, void *obj, int flags);
* - If OBJ_NODATA is set, ao2_callback will return NULL. No refcounts * - If OBJ_NODATA is set, ao2_callback will return NULL. No refcounts
* of any of the traversed objects will be incremented. * of any of the traversed objects will be incremented.
* On the converse, if it is NOT set (the default), the ref count * On the converse, if it is NOT set (the default), the ref count
* of the first matching object will be incremented and returned. If * of the first matching object will be incremented and returned.
* OBJ_MULTIPLE is set, the ref count of all matching objects will * - If OBJ_MULTIPLE is set, the ref count of all matching objects will
* be incremented in an iterator for a temporary container and returned. * 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. * to the objects in the bucket that the object key hashes to.
* \param cb_fn A function pointer, that will be called on all * \param cb_fn A function pointer, that will be called on all
* objects, to see if they match. This function returns CMP_MATCH * objects, to see if they match. This function returns CMP_MATCH
@ -1634,9 +1644,9 @@ void *__ao2_unlink(struct ao2_container *c, void *obj, int flags);
* functions such as find() do * functions such as find() do
* OBJ_MULTIPLE return multiple matches * OBJ_MULTIPLE return multiple matches
* Default is no. * Default is no.
* OBJ_POINTER the pointer is an object pointer * OBJ_SEARCH_OBJECT the pointer is to an object
* OBJ_KEY the pointer is to a search key * OBJ_SEARCH_KEY the pointer is to a search key
* OBJ_PARTIAL_KEY the pointer is to a partial 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 * \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. * be used to free the additional reference possibly created by this function.
@ -1673,9 +1683,9 @@ void *__ao2_callback(struct ao2_container *c, enum search_flags flags, ao2_callb
* allows the caller to pass in arbitrary data. * allows the caller to pass in arbitrary data.
* *
* This call would be used instead of ao2_callback() when the caller needs to pass * 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 * OBJ_SEARCH_OBJECT, OBJ_SEARCH_KEY, or OBJ_SEARCH_PARTIAL_KEY as part of the flags
* prototype ao2 object for 'arg') and also needs access to other non-global data * argument (which in turn requires passing in a known pointer type for 'arg') and
* to complete it's comparison or task. * 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 the documentation for ao2_callback() for argument descriptions.
* *

Write Preview
Loading…
Cancel
Save