Fri Jul 24 00:41:18 2009

Asterisk developer's documentation


astobj2.h File Reference

#include "asterisk/compat.h"

Go to the source code of this file.

Data Structures

struct  ao2_iterator
 When we need to walk through a container, we use ao2_iterator to keep track of the current position. The Astobj2 iterator. More...
struct  ao2_list
 Used as return value if the flag OBJ_MULTIPLE is set. More...

Object Containers

Here start declarations of containers.

#define ao2_container_alloc(arg1, arg2, arg3)   _ao2_container_alloc((arg1), (arg2), (arg3))
#define ao2_t_container_alloc(arg1, arg2, arg3, arg4)   _ao2_container_alloc((arg1), (arg2), (arg3))
 Allocate and initialize a container with the desired number of buckets.
ao2_container_ao2_container_alloc (const unsigned int n_buckets, ao2_hash_fn *hash_fn, ao2_callback_fn *cmp_fn)
ao2_container_ao2_container_alloc_debug (const unsigned int n_buckets, ao2_hash_fn *hash_fn, ao2_callback_fn *cmp_fn, char *tag, char *file, int line, const char *funcname)
int ao2_container_count (struct ao2_container *c)
 Returns the number of elements in a container.

Object Management

Here we have functions to manage objects.

We can use the functions below on any kind of object defined by the user.

#define ao2_link(arg1, arg2)   _ao2_link((arg1), (arg2))
#define ao2_t_link(arg1, arg2, arg3)   _ao2_link((arg1), (arg2))
 Add an object to a container.
#define ao2_t_unlink(arg1, arg2, arg3)   _ao2_unlink((arg1), (arg2))
 Remove an object from the container.
#define ao2_unlink(arg1, arg2)   _ao2_unlink((arg1), (arg2))
void * _ao2_link (struct ao2_container *c, void *newobj)
void * _ao2_link_debug (struct ao2_container *c, void *new_obj, char *tag, char *file, int line, const char *funcname)
void * _ao2_unlink (struct ao2_container *c, void *obj)
void * _ao2_unlink_debug (struct ao2_container *c, void *obj, char *tag, char *file, int line, const char *funcname)

Defines

#define ao2_alloc(arg1, arg2)   _ao2_alloc((arg1), (arg2))
#define ao2_callback(arg1, arg2, arg3, arg4)   _ao2_callback((arg1), (arg2), (arg3), (arg4))
#define ao2_find(arg1, arg2, arg3)   _ao2_find((arg1), (arg2), (arg3))
#define ao2_iterator_next(arg1)   _ao2_iterator_next((arg1))
#define ao2_ref(arg1, arg2)   _ao2_ref((arg1), (arg2))
#define ao2_t_alloc(arg1, arg2, arg3)   _ao2_alloc((arg1), (arg2))
 Allocate and initialize an object.
#define ao2_t_callback(arg1, arg2, arg3, arg4, arg5)   _ao2_callback((arg1), (arg2), (arg3), (arg4))
 ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below.
#define ao2_t_find(arg1, arg2, arg3, arg4)   _ao2_find((arg1), (arg2), (arg3))
#define ao2_t_iterator_next(arg1, arg2)   _ao2_iterator_next((arg1))
#define ao2_t_ref(arg1, arg2, arg3)   _ao2_ref((arg1), (arg2))
 Reference/unreference an object and return the old refcount.
#define F_AO2I_DONTLOCK   1

Typedefs

typedef int( ao2_callback_fn )(void *obj, void *arg, int flags)
 Type of a generic callback function.
typedef void(*) ao2_destructor_fn (void *)
 Typedef for an object destructor. This is called just before freeing the memory for the object. It is passed a pointer to the user-defined data of the object.
typedef int( ao2_hash_fn )(const void *obj, const int flags)

Enumerations

enum  _cb_results { CMP_MATCH = 0x1, CMP_STOP = 0x2 }
 A callback function will return a combination of CMP_MATCH and CMP_STOP. The latter will terminate the search in a container. More...
enum  search_flags { OBJ_UNLINK = (1 << 0), OBJ_NODATA = (1 << 1), OBJ_MULTIPLE = (1 << 2), OBJ_POINTER = (1 << 3) }
 Flags passed to ao2_callback() and ao2_hash_fn() to modify its behaviour. More...

Functions

void * _ao2_alloc (const size_t data_size, ao2_destructor_fn destructor_fn)
void * _ao2_alloc_debug (const size_t data_size, ao2_destructor_fn destructor_fn, char *tag, char *file, int line, const char *funcname)
void * _ao2_callback (struct ao2_container *c, enum search_flags flags, ao2_callback_fn *cb_fn, void *arg)
void * _ao2_callback_debug (struct ao2_container *c, enum search_flags flags, ao2_callback_fn *cb_fn, void *arg, char *tag, char *file, int line, const char *funcname)
void * _ao2_find (struct ao2_container *c, void *arg, enum search_flags flags)
void * _ao2_find_debug (struct ao2_container *c, void *arg, enum search_flags flags, char *tag, char *file, int line, const char *funcname)
void * _ao2_iterator_next (struct ao2_iterator *a)
void * _ao2_iterator_next_debug (struct ao2_iterator *a, char *tag, char *file, int line, const char *funcname)
int _ao2_ref (void *o, int delta)
int _ao2_ref_debug (void *o, int delta, char *tag, char *file, int line, const char *funcname)
void ao2_bt (void)
ao2_iterator ao2_iterator_init (struct ao2_container *c, int flags)
int ao2_lock (void *a)
 Lock an object.
void * ao2_object_get_lockaddr (void *obj)
 Return the lock address of an object.
int ao2_trylock (void *a)
 Try locking-- (don't block if fail).
int ao2_unlock (void *a)
 Unlock an object.

Variables

ao2_callback_fn ao2_match_by_addr
 a very common callback is one that matches by address.


Detailed Description

Object Model implementing objects and containers.

Definition in file astobj2.h.


Define Documentation

#define ao2_alloc ( arg1,
arg2   )     _ao2_alloc((arg1), (arg2))

Definition at line 411 of file astobj2.h.

Referenced by alloc_event_ref(), alloc_queue(), ast_odbc_request_obj(), ast_taskprocessor_get(), ast_tcptls_client_start(), ast_tcptls_server_root(), build_device(), build_peer(), build_profile(), build_route(), build_user(), conf_run(), create_parkinglot(), create_queue_member(), dialgroup_write(), get_filestream(), new_iax(), proxy_allocate(), pthread_timer_open(), set_fn(), try_calling(), and xml_translate().

#define ao2_callback ( arg1,
arg2,
arg3,
arg4   )     _ao2_callback((arg1), (arg2), (arg3), (arg4))

Definition at line 846 of file astobj2.h.

Referenced by ast_event_dump_cache(), ast_event_queue_and_cache(), delete_users(), do_timing(), load_config(), and load_module().

#define ao2_container_alloc ( arg1,
arg2,
arg3   )     _ao2_container_alloc((arg1), (arg2), (arg3))

Definition at line 681 of file astobj2.h.

Referenced by ast_event_init(), ast_features_init(), ast_tps_init(), config_text_file_save(), dialgroup_write(), init_queue(), load_module(), and xml_translate().

#define ao2_find ( arg1,
arg2,
arg3   )     _ao2_find((arg1), (arg2), (arg3))

Definition at line 863 of file astobj2.h.

Referenced by __find_callno(), ast_event_get_cached(), ast_taskprocessor_get(), authenticate_request(), authenticate_verify(), build_peer(), build_user(), compare_weight(), dialgroup_read(), dialgroup_write(), find_parkinglot(), find_peer(), find_profile(), find_pvt(), find_queue_by_name_rt(), find_timer(), find_user(), get_member_penalty(), handle_cli_iax2_unregister(), iax2_destroy_helper(), load_realtime_queue(), phoneprov_callback(), queue_function_queuememberlist(), queue_function_queuewaitingcount(), queue_function_var(), reload_queue_members(), reload_queues(), remove_from_queue(), set_fn(), update_queue(), and xml_translate().

#define ao2_iterator_next ( arg1   )     _ao2_iterator_next((arg1))

Definition at line 969 of file astobj2.h.

Referenced by __iax2_show_peers(), __queues_show(), ast_odbc_request_obj(), authenticate_reply(), check_access(), cli_console_active(), cli_list_devices(), cli_tps_report(), compare_weight(), complete_iax2_peers(), complete_iax2_unregister(), complete_queue(), complete_queue_remove_member(), complete_sip_user(), delete_profiles(), delete_routes(), delete_users(), destroy_pvts(), dialgroup_read(), do_parking_thread(), dump_queue_members(), free_members(), get_member_status(), handle_cli_iax2_show_users(), handle_cli_odbc_show(), handle_feature_show(), handle_parkedcalls(), handle_show_routes(), iax2_getpeername(), iax2_getpeertrunk(), interface_exists(), interface_exists_global(), manager_iax2_show_peer_list(), manager_parking_status(), manager_queues_status(), manager_queues_summary(), num_available_members(), poke_all_peers(), pp_each_user_exec(), prune_peers(), prune_users(), queue_function_qac(), queue_function_qac_dep(), queue_function_queuememberlist(), reload(), reload_queues(), rt_handle_member_record(), set_member_paused(), set_member_penalty(), sip_show_users(), stop_streams(), tps_taskprocessor_tab_complete(), try_calling(), unload_module(), update_queue(), update_realtime_members(), and update_status().

#define ao2_link ( arg1,
arg2   )     _ao2_link((arg1), (arg2))

Definition at line 725 of file astobj2.h.

Referenced by add_to_queue(), ast_event_dup_and_cache(), ast_odbc_request_obj(), ast_taskprocessor_get(), ast_taskprocessor_unreference(), build_device(), build_parkinglot(), build_route(), dialgroup_write(), odbc_register_class(), pthread_timer_open(), reload_queues(), rt_handle_member_record(), set_config(), set_fn(), store_by_peercallno(), store_by_transfercallno(), and xml_translate().

#define ao2_ref ( arg1,
arg2   )     _ao2_ref((arg1), (arg2))

Definition at line 444 of file astobj2.h.

Referenced by __find_callno(), __queues_show(), __sip_destroy(), __unload_module(), _sip_tcp_helper_thread(), add_to_queue(), alloc_queue(), announce_thread(), ast_closestream(), ast_event_dup_and_cache(), ast_event_get_cached(), ast_filestream_frame_freed(), ast_odbc_release_obj(), ast_odbc_request_obj(), ast_readaudio_callback(), ast_readframe(), ast_readvideo_callback(), ast_taskprocessor_get(), ast_taskprocessor_unreference(), ast_tcptls_client_start(), ast_tcptls_server_root(), cli_tps_ping(), cli_tps_report(), compare_weight(), complete_queue_remove_member(), conf_free(), conf_run(), config_text_file_save(), copy_socket_data(), destroy_queue(), dialgroup_read(), dialgroup_write(), dialog_ref(), dialog_unref(), do_parking_thread(), dump_queue_members(), end_bridge_callback(), end_bridge_callback_data_fixup(), free_members(), get_member_penalty(), get_member_status(), group_destroy(), handle_cli_iax2_set_debug(), handle_cli_odbc_show(), handle_event(), handle_feature_show(), handle_parkedcalls(), handle_tls_connection(), hangupcalls(), httpd_helper_thread(), iax2_destroy(), interface_exists(), interface_exists_global(), load_module(), manager_parking_status(), manager_queues_status(), manager_queues_summary(), new_iax(), num_available_members(), odbc_class_destructor(), odbc_obj_destructor(), parkinglot_addref(), parkinglot_unref(), parse_moved_contact(), peer_ref(), peer_unref(), pthread_timer_ack(), pthread_timer_close(), pthread_timer_disable_continuous(), pthread_timer_enable_continuous(), pthread_timer_get_event(), pthread_timer_open(), pthread_timer_set_rate(), queue_function_qac(), queue_function_qac_dep(), queue_function_queuememberlist(), queue_ref(), queue_unref(), ref_proxy(), ref_pvt(), reload(), reload_queues(), remove_from_queue(), rt_handle_member_record(), set_member_paused(), set_member_penalty(), sip_destroy_peer(), sip_prepare_socket(), sip_tcp_locate(), tps_taskprocessor_tab_complete(), try_calling(), unload_module(), unref_profile(), unref_pvt(), unref_route(), unref_user(), update_queue(), update_realtime_members(), update_status(), user_ref(), user_unref(), and xml_translate().

#define ao2_t_alloc ( arg1,
arg2,
arg3   )     _ao2_alloc((arg1), (arg2))

Allocate and initialize an object.

Parameters:
data_size The sizeof() of the user-defined structure.
destructor_fn The destructor function (can be NULL)
Returns:
A pointer to user-data.
Allocates a struct astobj2 with sufficient space for the user-defined structure.
Note:
  • storage is zeroed; XXX maybe we want a flag to enable/disable this.
  • the refcount of the object just created is 1
  • the returned pointer cannot be free()'d or realloc()'ed; rather, we just call ao2_ref(o, -1);

Definition at line 410 of file astobj2.h.

Referenced by build_peer(), moh_class_malloc(), sip_alloc(), and temp_peer().

#define ao2_t_callback ( arg1,
arg2,
arg3,
arg4,
arg5   )     _ao2_callback((arg1), (arg2), (arg3), (arg4))

ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below.

Parameters:
c A pointer to the container to operate on.
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.
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).
arg passed to the callback.
Returns:
A pointer to the object found/marked, a pointer to a list of objects matching comparison function, NULL if not found.
If the function returns any objects, their refcount is incremented, and the caller is in charge of decrementing them once done. Also, in case of multiple values returned, the list used to store the objects must be freed by the caller.

Typically, ao2_callback() is used for two purposes:

This function searches through a container and performs operations on objects according on flags passed. XXX describe better The comparison is done calling the compare function set implicitly. The p pointer can be a pointer to an object or to a key, we can say this looking at flags value. If p points to an object we will search for the object pointed by this value, otherwise we serch for a key value. If the key is not uniq we only find the first matching valued. If we use the OBJ_MARK flags, we mark all the objects matching the condition.

The use of flags argument is the follow:

OBJ_UNLINK unlinks the object found OBJ_NODATA on match, do return an object Callbacks use OBJ_NODATA as a default functions such as find() do OBJ_MULTIPLE return multiple matches Default for _find() is no. to a key (not yet supported) OBJ_POINTER the pointer is an object pointer

In case we return a list, the callee must take care to destroy that list when no longer used.

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.

Definition at line 845 of file astobj2.h.

Referenced by ast_moh_destroy(), do_monitor(), find_call(), find_peer(), get_mohbydigit(), load_moh_classes(), reload_config(), sip_do_reload(), sip_prune_realtime(), sip_show_channels(), sip_show_channelstats(), sip_show_objects(), and unload_module().

#define ao2_t_container_alloc ( arg1,
arg2,
arg3,
arg4   )     _ao2_container_alloc((arg1), (arg2), (arg3))

Allocate and initialize a container with the desired number of buckets.

We allocate space for a struct astobj_container, struct container and the buckets[] array.

Parameters:
n_buckets Number of buckets for hash
hash_fn Pointer to a function computing a hash value.
cmp_fn Pointer to a function comparating key-value with a string. (can be NULL)
Returns:
A pointer to a struct container.
destructor is set implicitly.

Definition at line 680 of file astobj2.h.

Referenced by load_module().

#define ao2_t_find ( arg1,
arg2,
arg3,
arg4   )     _ao2_find((arg1), (arg2), (arg3))

ao2_find() is a short hand for ao2_callback(c, flags, c->cmp_fn, arg) XXX possibly change order of arguments ?

Definition at line 862 of file astobj2.h.

Referenced by build_peer(), find_call(), find_peer(), get_mohbyname(), get_sip_pvt_byid_locked(), and sip_prune_realtime().

#define ao2_t_iterator_next ( arg1,
arg2   )     _ao2_iterator_next((arg1))

Definition at line 968 of file astobj2.h.

Referenced by _sip_show_peers(), complete_sip_peer(), complete_sip_registered_peer(), complete_sipch(), handle_cli_moh_show_classes(), handle_cli_moh_show_files(), handle_request_subscribe(), sip_poke_all_peers(), sip_prune_realtime(), sip_show_channel(), sip_show_history(), sip_show_inuse(), and unload_module().

#define ao2_t_link ( arg1,
arg2,
arg3   )     _ao2_link((arg1), (arg2))

Add an object to a container.

Parameters:
c the container to operate on.
newobj the object to be added.
Return values:
NULL on errors
newobj on success.
This function inserts an object in a container according its key.

Note:
Remember to set the key before calling this function.

This function automatically increases the reference count to account for the reference that the container now holds to the object.

Definition at line 724 of file astobj2.h.

Referenced by create_addr_from_peer(), manager_sipnotify(), moh_register(), parse_register_contact(), register_verify(), sip_alloc(), sip_cli_notify(), sip_poke_peer(), sip_prune_realtime(), sip_request_call(), and sip_send_mwi_to_peer().

#define ao2_t_ref ( arg1,
arg2,
arg3   )     _ao2_ref((arg1), (arg2))

Reference/unreference an object and return the old refcount.

Parameters:
o A pointer to the object
delta Value to add to the reference counter.
Returns:
The value of the reference counter before the operation.
Increase/decrease the reference counter according the value of delta.

If the refcount goes to zero, the object is destroyed.

Note:
The object must not be locked by the caller of this function, as it is invalid to try to unlock it after releasing the reference.

if we know the pointer to an object, it is because we have a reference count to it, so the only case when the object can go away is when we release our reference, and it is the last one in existence.

Definition at line 443 of file astobj2.h.

Referenced by check_peer_ok(), dialog_dump_func(), handle_request_do(), handle_request_subscribe(), local_attended_transfer(), peer_dump_func(), ref_peer(), sip_alloc(), sip_show_channel(), sip_show_history(), unload_module(), and unref_peer().

#define ao2_t_unlink ( arg1,
arg2,
arg3   )     _ao2_unlink((arg1), (arg2))

Remove an object from the container.

Parameters:
c the container
obj the object to unlink
Return values:
NULL,always 
Note:
The object requested to be unlinked must be valid. However, if it turns out that it is not in the container, this function is still safe to be called.

If the object gets unlinked from the container, the container's reference to the object will be automatically released. (The refcount will be decremented).

Definition at line 750 of file astobj2.h.

Referenced by create_addr_from_peer(), dialog_unlink_all(), expire_register(), manager_sipnotify(), parse_register_contact(), sip_cli_notify(), sip_poke_peer(), sip_prune_realtime(), sip_request_call(), and sip_send_mwi_to_peer().

#define ao2_unlink ( arg1,
arg2   )     _ao2_unlink((arg1), (arg2))

Definition at line 751 of file astobj2.h.

Referenced by ast_taskprocessor_unreference(), build_user(), delete_profiles(), delete_routes(), delete_users(), destroy_pvts(), dialgroup_write(), find_queue_by_name_rt(), free_members(), handle_cli_iax2_prune_realtime(), leave_queue(), parkinglot_destroy(), prune_users(), reload(), reload_queues(), remove_by_peercallno(), remove_by_transfercallno(), remove_from_queue(), unlink_peer(), unload_module(), and update_realtime_members().

#define F_AO2I_DONTLOCK   1

don't lock when iterating

Definition at line 948 of file astobj2.h.

Referenced by __ao2_iterator_next(), __queues_show(), _ao2_iterator_next(), _ao2_iterator_next_debug(), interface_exists_global(), and reload_queues().


Typedef Documentation

typedef int( ao2_callback_fn)(void *obj, void *arg, int flags)

Type of a generic callback function.

Parameters:
obj pointer to the (user-defined part) of an object.
arg callback argument from ao2_callback()
flags flags from ao2_callback()
The return values are a combination of enum _cb_results. Callback functions are used to search or manipulate objects in a container,

Definition at line 609 of file astobj2.h.

typedef void(*) ao2_destructor_fn(void *)

Typedef for an object destructor. This is called just before freeing the memory for the object. It is passed a pointer to the user-defined data of the object.

Definition at line 383 of file astobj2.h.

typedef int( ao2_hash_fn)(const void *obj, const int flags)

Type of a generic function to generate a hash value from an object. flags is ignored at the moment. Eventually, it will include the value of OBJ_POINTER passed to ao2_callback().

Definition at line 652 of file astobj2.h.


Enumeration Type Documentation

enum _cb_results

A callback function will return a combination of CMP_MATCH and CMP_STOP. The latter will terminate the search in a container.

Enumerator:
CMP_MATCH  the object matches the request
CMP_STOP  stop the search now

Definition at line 618 of file astobj2.h.

00618                  {
00619    CMP_MATCH   = 0x1,   /*!< the object matches the request */
00620    CMP_STOP = 0x2,   /*!< stop the search now */
00621 };

enum search_flags

Flags passed to ao2_callback() and ao2_hash_fn() to modify its behaviour.

Enumerator:
OBJ_UNLINK  Unlink the object for which the callback function returned CMP_MATCH . This is the only way to extract objects from a container.
OBJ_NODATA  On match, don't return the object hence do not increase its refcount.
OBJ_MULTIPLE  Don't stop at the first match in ao2_callback()
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_POINTER  obj is an object of the same type as the one being searched for, so use the object's hash function for optimized searching. The search function is unaffected (i.e. use the one passed as argument, or match_by_addr if none specified).

Definition at line 626 of file astobj2.h.

00626                   {
00627    /*! Unlink the object for which the callback function
00628     *  returned CMP_MATCH . This is the only way to extract
00629     *  objects from a container. */
00630    OBJ_UNLINK   = (1 << 0),
00631    /*! On match, don't return the object hence do not increase
00632     *  its refcount. */
00633    OBJ_NODATA   = (1 << 1),
00634    /*! Don't stop at the first match in ao2_callback()
00635     *  \note This is not fully implemented.   Using OBJ_MULTIME with OBJ_NODATA
00636     *  is perfectly fine.  The part that is not implemented is the case where
00637     *  multiple objects should be returned by ao2_callback().
00638     */
00639    OBJ_MULTIPLE = (1 << 2),
00640    /*! obj is an object of the same type as the one being searched for,
00641     *  so use the object's hash function for optimized searching.
00642     *  The search function is unaffected (i.e. use the one passed as
00643     *  argument, or match_by_addr if none specified). */
00644    OBJ_POINTER  = (1 << 3),
00645 };


Function Documentation

void* _ao2_alloc ( const size_t  data_size,
ao2_destructor_fn  destructor_fn 
)

Definition at line 350 of file astobj2.c.

References __ao2_alloc().

Referenced by _ao2_container_alloc().

00351 {
00352    return __ao2_alloc(data_size, destructor_fn);
00353 }

void* _ao2_alloc_debug ( const size_t  data_size,
ao2_destructor_fn  destructor_fn,
char *  tag,
char *  file,
int  line,
const char *  funcname 
)

Definition at line 330 of file astobj2.c.

References __ao2_alloc(), and REF_FILE.

Referenced by _ao2_container_alloc_debug().

00331 {
00332    /* allocation */
00333    void *obj;
00334    FILE *refo = fopen(REF_FILE,"a");
00335 
00336    obj = __ao2_alloc(data_size, destructor_fn);
00337 
00338    if (obj == NULL)
00339       return NULL;
00340    
00341    if (refo) {
00342       fprintf(refo, "%p =1   %s:%d:%s (%s)\n", obj, file, line, funcname, tag);
00343       fclose(refo);
00344    }
00345 
00346    /* return a pointer to the user data */
00347    return obj;
00348 }

void* _ao2_callback ( struct ao2_container c,
enum search_flags  flags,
ao2_callback_fn cb_fn,
void *  arg 
)

Definition at line 691 of file astobj2.c.

References __ao2_callback().

Referenced by _ao2_find(), _ao2_unlink(), and container_destruct().

00693 {
00694    return __ao2_callback(c,flags, cb_fn, arg, NULL, NULL, 0, NULL);
00695 }

void* _ao2_callback_debug ( struct ao2_container c,
enum search_flags  flags,
ao2_callback_fn cb_fn,
void *  arg,
char *  tag,
char *  file,
int  line,
const char *  funcname 
)

Definition at line 683 of file astobj2.c.

References __ao2_callback().

Referenced by _ao2_find_debug(), _ao2_unlink_debug(), and container_destruct_debug().

00687 {
00688    return __ao2_callback(c,flags, cb_fn, arg, tag, file, line, funcname);
00689 }

struct ao2_container* _ao2_container_alloc ( const unsigned int  n_buckets,
ao2_hash_fn hash_fn,
ao2_callback_fn cmp_fn 
)

Definition at line 449 of file astobj2.c.

References __ao2_container_alloc(), _ao2_alloc(), container_destruct(), and ao2_container::n_buckets.

00451 {
00452    /* XXX maybe consistency check on arguments ? */
00453    /* compute the container size */
00454 
00455    size_t container_size = sizeof(struct ao2_container) + n_buckets * sizeof(struct bucket);
00456    struct ao2_container *c = _ao2_alloc(container_size, container_destruct);
00457 
00458    return __ao2_container_alloc(c, n_buckets, hash_fn, cmp_fn);
00459 }

struct ao2_container* _ao2_container_alloc_debug ( const unsigned int  n_buckets,
ao2_hash_fn hash_fn,
ao2_callback_fn cmp_fn,
char *  tag,
char *  file,
int  line,
const char *  funcname 
)

Definition at line 437 of file astobj2.c.

References __ao2_container_alloc(), _ao2_alloc_debug(), container_destruct_debug(), and ao2_container::n_buckets.

00439 {
00440    /* XXX maybe consistency check on arguments ? */
00441    /* compute the container size */
00442    size_t container_size = sizeof(struct ao2_container) + n_buckets * sizeof(struct bucket);
00443    struct ao2_container *c = _ao2_alloc_debug(container_size, container_destruct_debug, tag, file, line, funcname);
00444 
00445    return __ao2_container_alloc(c, n_buckets, hash_fn, cmp_fn);
00446 }

void* _ao2_find ( struct ao2_container c,
void *  arg,
enum search_flags  flags 
)

Definition at line 705 of file astobj2.c.

References _ao2_callback(), and ao2_container::cmp_fn.

00706 {
00707    return _ao2_callback(c, flags, c->cmp_fn, arg);
00708 }

void* _ao2_find_debug ( struct ao2_container c,
void *  arg,
enum search_flags  flags,
char *  tag,
char *  file,
int  line,
const char *  funcname 
)

the find function just invokes the default callback with some reasonable flags.

Definition at line 700 of file astobj2.c.

References _ao2_callback_debug(), and ao2_container::cmp_fn.

00701 {
00702    return _ao2_callback_debug(c, flags, c->cmp_fn, arg, tag, file, line, funcname);
00703 }

void* _ao2_iterator_next ( struct ao2_iterator a  ) 

Definition at line 799 of file astobj2.c.

References __ao2_iterator_next(), _ao2_ref(), ao2_unlock(), ao2_iterator::c, F_AO2I_DONTLOCK, and ao2_iterator::flags.

00800 {
00801    struct bucket_list *p = NULL;
00802    void *ret = NULL;
00803 
00804    ret = __ao2_iterator_next(a, &p);
00805    
00806    if (p) {
00807       /* inc refcount of returned object */
00808       _ao2_ref(ret, 1);
00809    }
00810 
00811    if (!(a->flags & F_AO2I_DONTLOCK))
00812       ao2_unlock(a->c);
00813 
00814    return ret;
00815 }

void* _ao2_iterator_next_debug ( struct ao2_iterator a,
char *  tag,
char *  file,
int  line,
const char *  funcname 
)

Definition at line 781 of file astobj2.c.

References __ao2_iterator_next(), _ao2_ref_debug(), ao2_unlock(), ao2_iterator::c, F_AO2I_DONTLOCK, and ao2_iterator::flags.

00782 {
00783    struct bucket_list *p;
00784    void *ret = NULL;
00785 
00786    ret = __ao2_iterator_next(a, &p);
00787    
00788    if (p) {
00789       /* inc refcount of returned object */
00790       _ao2_ref_debug(ret, 1, tag, file, line, funcname);
00791    }
00792 
00793    if (!(a->flags & F_AO2I_DONTLOCK))
00794       ao2_unlock(a->c);
00795 
00796    return ret;
00797 }

void* _ao2_link ( struct ao2_container c,
void *  newobj 
)

Definition at line 525 of file astobj2.c.

References __ao2_link(), _ao2_ref(), and ao2_unlock().

00526 {
00527    struct bucket_list *p = __ao2_link(c, user_data);
00528    
00529    if (p) {
00530       _ao2_ref(user_data, +1);
00531       ao2_unlock(c);
00532    }
00533    return p;
00534 }

void* _ao2_link_debug ( struct ao2_container c,
void *  new_obj,
char *  tag,
char *  file,
int  line,
const char *  funcname 
)

Definition at line 514 of file astobj2.c.

References __ao2_link(), _ao2_ref_debug(), and ao2_unlock().

00515 {
00516    struct bucket_list *p = __ao2_link(c, user_data);
00517    
00518    if (p) {
00519       _ao2_ref_debug(user_data, +1, tag, file, line, funcname);
00520       ao2_unlock(c);
00521    }
00522    return p;
00523 }

int _ao2_ref ( void *  o,
int  delta 
)

Definition at line 245 of file astobj2.c.

References __ao2_ref(), and INTERNAL_OBJ().

Referenced by __ao2_callback(), _ao2_iterator_next(), _ao2_link(), and cd_cb().

00246 {
00247    struct astobj2 *obj = INTERNAL_OBJ(user_data);
00248 
00249    if (obj == NULL)
00250       return -1;
00251 
00252    return __ao2_ref(user_data, delta);
00253 }

int _ao2_ref_debug ( void *  o,
int  delta,
char *  tag,
char *  file,
int  line,
const char *  funcname 
)

Definition at line 225 of file astobj2.c.

References __ao2_ref(), __priv_data::destructor_fn, INTERNAL_OBJ(), astobj2::priv_data, __priv_data::ref_counter, and REF_FILE.

Referenced by __ao2_callback(), _ao2_iterator_next_debug(), _ao2_link_debug(), and cd_cb_debug().

00226 {
00227    struct astobj2 *obj = INTERNAL_OBJ(user_data);
00228    
00229    if (obj == NULL)
00230       return -1;
00231 
00232    if (delta != 0) {
00233       FILE *refo = fopen(REF_FILE,"a");
00234       fprintf(refo, "%p %s%d   %s:%d:%s (%s) [@%d]\n", user_data, (delta<0? "":"+"), delta, file, line, funcname, tag, obj->priv_data.ref_counter);
00235       fclose(refo);
00236    }
00237    if (obj->priv_data.ref_counter + delta == 0 && obj->priv_data.destructor_fn != NULL) { /* this isn't protected with lock; just for o/p */
00238          FILE *refo = fopen(REF_FILE,"a");    
00239          fprintf(refo, "%p **call destructor** %s:%d:%s (%s)\n", user_data, file, line, funcname, tag);   
00240          fclose(refo);
00241    }
00242    return __ao2_ref(user_data, delta);
00243 }

void* _ao2_unlink ( struct ao2_container c,
void *  obj 
)

Definition at line 559 of file astobj2.c.

References _ao2_callback(), ao2_match_by_addr, INTERNAL_OBJ(), OBJ_NODATA, OBJ_POINTER, and OBJ_UNLINK.

00560 {
00561    if (INTERNAL_OBJ(user_data) == NULL)   /* safety check on the argument */
00562       return NULL;
00563 
00564    _ao2_callback(c, OBJ_UNLINK | OBJ_POINTER | OBJ_NODATA, ao2_match_by_addr, user_data);
00565 
00566    return NULL;
00567 }

void* _ao2_unlink_debug ( struct ao2_container c,
void *  obj,
char *  tag,
char *  file,
int  line,
const char *  funcname 
)

Definition at line 548 of file astobj2.c.

References _ao2_callback_debug(), ao2_match_by_addr, INTERNAL_OBJ(), OBJ_NODATA, OBJ_POINTER, and OBJ_UNLINK.

00550 {
00551    if (INTERNAL_OBJ(user_data) == NULL)   /* safety check on the argument */
00552       return NULL;
00553 
00554    _ao2_callback_debug(c, OBJ_UNLINK | OBJ_POINTER | OBJ_NODATA, ao2_match_by_addr, user_data, tag, file, line, funcname);
00555 
00556    return NULL;
00557 }

void ao2_bt ( void   ) 

Definition at line 83 of file astobj2.c.

References ast_verbose, free, and N1.

00084 {
00085    int c, i;
00086 #define N1  20
00087    void *addresses[N1];
00088    char **strings;
00089 
00090    c = backtrace(addresses, N1);
00091    strings = backtrace_symbols(addresses,c);
00092    ast_verbose("backtrace returned: %d\n", c);
00093    for(i = 0; i < c; i++) {
00094       ast_verbose("%d: %p %s\n", i, addresses[i], strings[i]);
00095    }
00096    free(strings);
00097 }

int ao2_container_count ( struct ao2_container c  ) 

Returns the number of elements in a container.

return the number of elements in the container

Definition at line 464 of file astobj2.c.

References ao2_container::elements.

Referenced by __queues_show(), _sip_show_peers(), cli_tps_report(), do_timing(), and pthread_timer_open().

00465 {
00466    return c->elements;
00467 }

struct ao2_iterator ao2_iterator_init ( struct ao2_container c,
int  flags 
)

initialize an iterator so we start from the first object

Definition at line 713 of file astobj2.c.

References ao2_iterator::c, and ao2_iterator::flags.

Referenced by __iax2_show_peers(), __queues_show(), _sip_show_peers(), ast_odbc_request_obj(), authenticate_reply(), check_access(), cli_console_active(), cli_list_devices(), cli_tps_report(), compare_weight(), complete_iax2_peers(), complete_iax2_unregister(), complete_queue(), complete_queue_remove_member(), complete_sip_peer(), complete_sip_registered_peer(), complete_sip_user(), complete_sipch(), delete_profiles(), delete_routes(), delete_users(), destroy_pvts(), dialgroup_read(), do_parking_thread(), dump_queue_members(), free_members(), get_member_status(), handle_cli_iax2_show_users(), handle_cli_moh_show_classes(), handle_cli_moh_show_files(), handle_cli_odbc_show(), handle_feature_show(), handle_parkedcalls(), handle_request_subscribe(), handle_show_routes(), iax2_getpeername(), iax2_getpeertrunk(), interface_exists(), interface_exists_global(), manager_iax2_show_peer_list(), manager_parking_status(), manager_queues_status(), manager_queues_summary(), num_available_members(), poke_all_peers(), pp_each_user_exec(), prune_peers(), prune_users(), queue_function_qac(), queue_function_qac_dep(), queue_function_queuememberlist(), reload(), reload_queues(), rt_handle_member_record(), set_member_paused(), set_member_penalty(), sip_poke_all_peers(), sip_prune_realtime(), sip_show_channel(), sip_show_history(), sip_show_inuse(), sip_show_users(), stop_streams(), tps_taskprocessor_tab_complete(), try_calling(), unload_module(), update_queue(), update_realtime_members(), and update_status().

00714 {
00715    struct ao2_iterator a = {
00716       .c = c,
00717       .flags = flags
00718    };
00719    
00720    return a;
00721 }

int ao2_lock ( void *  a  ) 

Lock an object.

Parameters:
a A pointer to the object we want to lock.
Returns:
0 on success, other values on error.

Definition at line 143 of file astobj2.c.

References ast_atomic_fetchadd_int(), ast_mutex_lock(), INTERNAL_OBJ(), __priv_data::lock, and astobj2::priv_data.

Referenced by __ao2_callback(), __ao2_iterator_next(), __ao2_link(), __queues_show(), _sip_show_peers(), add_to_queue(), ast_taskprocessor_get(), ast_taskprocessor_unreference(), build_parkinglot(), compare_weight(), complete_queue_remove_member(), complete_sip_user(), dialog_needdestroy(), end_bridge_callback(), find_call(), find_queue_by_name_rt(), get_member_penalty(), get_member_status(), handle_request_subscribe(), interface_exists_global(), is_our_turn(), join_queue(), leave_queue(), load_config(), load_realtime_queue(), manager_queues_status(), manager_queues_summary(), moh_release(), mohalloc(), monmp3thread(), mwi_event_cb(), pthread_timer_disable_continuous(), pthread_timer_enable_continuous(), pthread_timer_open(), pthread_timer_set_rate(), queue_function_qac(), queue_function_qac_dep(), queue_function_queuememberlist(), queue_function_queuewaitingcount(), queue_function_var(), recalc_holdtime(), record_abandoned(), reload_queue_members(), reload_queues(), remove_from_queue(), ring_entry(), run_timer(), set_member_paused(), set_member_penalty(), sip_poke_all_peers(), sip_prune_realtime(), sip_show_inuse(), sip_show_user(), sip_show_users(), try_calling(), update_call_counter(), update_queue(), update_realtime_members(), and update_status().

00147 {
00148    struct astobj2 *p = INTERNAL_OBJ(user_data);
00149 
00150    if (p == NULL)
00151       return -1;
00152 
00153 #ifdef AO2_DEBUG
00154    ast_atomic_fetchadd_int(&ao2.total_locked, 1);
00155 #endif
00156 
00157 #ifndef DEBUG_THREADS
00158    return ast_mutex_lock(&p->priv_data.lock);
00159 #else
00160    return __ast_pthread_mutex_lock(file, line, func, var, &p->priv_data.lock);
00161 #endif
00162 }

void* ao2_object_get_lockaddr ( void *  obj  ) 

Return the lock address of an object.

Parameters:
[in] obj A pointer to the object we want.
Returns:
the address of the lock, else NULL.
This function comes in handy mainly for debugging locking situations, where the locking trace code reports the lock address, this allows you to correlate against object address, to match objects to reported locks.

Since:
1.6.1

Definition at line 210 of file astobj2.c.

References INTERNAL_OBJ(), __priv_data::lock, and astobj2::priv_data.

00211 {
00212    struct astobj2 *p = INTERNAL_OBJ(obj);
00213    
00214    if (p == NULL)
00215       return NULL;
00216 
00217    return &p->priv_data.lock;
00218 }

int ao2_trylock ( void *  a  ) 

Try locking-- (don't block if fail).

Parameters:
a A pointer to the object we want to lock.
Returns:
0 on success, other values on error.

Definition at line 187 of file astobj2.c.

References ast_atomic_fetchadd_int(), ast_mutex_trylock(), INTERNAL_OBJ(), __priv_data::lock, and astobj2::priv_data.

00191 {
00192    struct astobj2 *p = INTERNAL_OBJ(user_data);
00193    int ret;
00194    
00195    if (p == NULL)
00196       return -1;
00197 #ifndef DEBUG_THREADS
00198    ret = ast_mutex_trylock(&p->priv_data.lock);
00199 #else
00200    ret = __ast_pthread_mutex_trylock(file, line, func, var, &p->priv_data.lock);
00201 #endif
00202 
00203 #ifdef AO2_DEBUG
00204    if (!ret)
00205       ast_atomic_fetchadd_int(&ao2.total_locked, 1);
00206 #endif
00207    return ret;
00208 }

int ao2_unlock ( void *  a  ) 

Unlock an object.

Parameters:
a A pointer to the object we want unlock.
Returns:
0 on success, other values on error.

Definition at line 165 of file astobj2.c.

References ast_atomic_fetchadd_int(), ast_mutex_unlock(), INTERNAL_OBJ(), __priv_data::lock, and astobj2::priv_data.

Referenced by __ao2_callback(), __queues_show(), _ao2_iterator_next(), _ao2_iterator_next_debug(), _ao2_link(), _ao2_link_debug(), _sip_show_peers(), add_to_queue(), ast_taskprocessor_get(), ast_taskprocessor_unreference(), build_parkinglot(), compare_weight(), complete_queue_remove_member(), complete_sip_user(), dialog_needdestroy(), end_bridge_callback(), find_call(), find_queue_by_name_rt(), get_member_penalty(), get_member_status(), handle_request_subscribe(), interface_exists_global(), is_our_turn(), join_queue(), leave_queue(), load_config(), load_realtime_queue(), manager_queues_status(), manager_queues_summary(), moh_release(), mohalloc(), monmp3thread(), mwi_event_cb(), pthread_timer_disable_continuous(), pthread_timer_enable_continuous(), pthread_timer_open(), pthread_timer_set_rate(), queue_function_qac(), queue_function_qac_dep(), queue_function_queuememberlist(), queue_function_queuewaitingcount(), queue_function_var(), recalc_holdtime(), record_abandoned(), reload_queue_members(), reload_queues(), remove_from_queue(), ring_entry(), run_timer(), set_member_paused(), set_member_penalty(), sip_poke_all_peers(), sip_prune_realtime(), sip_show_inuse(), sip_show_user(), sip_show_users(), try_calling(), update_call_counter(), update_queue(), update_realtime_members(), and update_status().

00169 {
00170    struct astobj2 *p = INTERNAL_OBJ(user_data);
00171 
00172    if (p == NULL)
00173       return -1;
00174 
00175 #ifdef AO2_DEBUG
00176    ast_atomic_fetchadd_int(&ao2.total_locked, -1);
00177 #endif
00178 
00179 #ifndef DEBUG_THREADS
00180    return ast_mutex_unlock(&p->priv_data.lock);
00181 #else
00182    return __ast_pthread_mutex_unlock(file, line, func, var, &p->priv_data.lock);
00183 #endif
00184 }


Variable Documentation

ao2_callback_fn ao2_match_by_addr

a very common callback is one that matches by address.

Definition at line 612 of file astobj2.h.

Referenced by _ao2_unlink(), _ao2_unlink_debug(), and load_module().


Generated on Fri Jul 24 00:41:18 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7