The container comparison functions historically only had the following flag to optimize a container search:
OBJ_POINTER. Asterisk 11 added the additional flag to simplify places that requested code searches:
OBJ_KEY. Now with the ability to have sorted containers - such as red-black trees - a third flag is available:
OBJ_PARTIAL_KEY. These three flags cannot be used at the same time.
There is a lot of historical code that does simple bit tests and sets. This code needs to be changed to take into account the fact that there are new search flags and must guard against their use if they are not supported by the container. Most of the adjustments are needed by the
ao2_callback_fn functions of the containers.
The following code templates should be used to implement the container callback functions. The templates use string keys but can be adapted for different types of keys.
Some slight renaming for consistency
A slight change to astobj2 for Asterisk 12 made these flags an enumerated flag field like the
OBJ_ORDER_xxx field so the names can indicate they are related to each other. The following are the new names:
OBJ_SEARCH_MASK- Bit mask to isolate the bit field in the flags.
OBJ_SEARCH_NONE- The arg pointer has no meaning to the astobj2 code.
OBJ_SEARCH_OBJECT- The arg pointer points to an object that can be stored in the container.
OBJ_SEARCH_KEY- The arg pointer points to a key value used by the container.
OBJ_SEARCH_PARTIAL_KEY- The arg pointer points to a partial key value used by the container.
OBJ_POINTER is defined as
OBJ_KEY is defined as
OBJ_PARTIAL_KEY is defined as
The old names are still available but deprecated until all code is converted to use the new names.
Sorted vs. Unsorted Container Searching
The sort/hash comparison functions act as a filter before the
ao2_callback_fn function is called. Every object is matched first by the sort/hash functions. This callback just adds additional discrimination between otherwise equal matches. For most sorted container searches you won't need a special callback and can use the default to match everything by passing NULL for this function.
However, with OBJ_CONTINUE, the sort/hash functions are only used to find the starting point in a container traversal of all objects.
This function should not return CMP_STOP unless you never want a container search to find multiple objects with the OBJ_MULTIPLE flag.
Sorted container cmp function
Unsorted containers must do more work selecting objects since traversals will either traverse the whole container or one hash bucket.