Thu Apr 28 2011 16:56:41

Asterisk developer's documentation


astobj2.c

Go to the documentation of this file.
00001 /*
00002  * astobj2 - replacement containers for asterisk data structures.
00003  *
00004  * Copyright (C) 2006 Marta Carbone, Luigi Rizzo - Univ. di Pisa, Italy
00005  *
00006  * See http://www.asterisk.org for more information about
00007  * the Asterisk project. Please do not directly contact
00008  * any of the maintainers of this project for assistance;
00009  * the project provides a web site, mailing lists and IRC
00010  * channels for your use.
00011  *
00012  * This program is free software, distributed under the terms of
00013  * the GNU General Public License Version 2. See the LICENSE file
00014  * at the top of the source tree.
00015  */
00016 
00017 /*
00018  * Function implementing astobj2 objects.
00019  */
00020 #include "asterisk.h"
00021 
00022 ASTERISK_FILE_VERSION(__FILE__, "$Revision: 298957 $")
00023 
00024 #include "asterisk/_private.h"
00025 #include "asterisk/astobj2.h"
00026 #include "asterisk/utils.h"
00027 #include "asterisk/cli.h"
00028 #define REF_FILE "/tmp/refs"
00029 
00030 /*!
00031  * astobj2 objects are always preceded by this data structure,
00032  * which contains a lock, a reference counter,
00033  * the flags and a pointer to a destructor.
00034  * The refcount is used to decide when it is time to
00035  * invoke the destructor.
00036  * The magic number is used for consistency check.
00037  * XXX the lock is not always needed, and its initialization may be
00038  * expensive. Consider making it external.
00039  */
00040 struct __priv_data {
00041    ast_mutex_t lock;
00042    int ref_counter;
00043    ao2_destructor_fn destructor_fn;
00044    /*! for stats */
00045    size_t data_size;
00046    /*! magic number.  This is used to verify that a pointer passed in is a
00047     *  valid astobj2 */
00048    uint32_t magic;
00049 };
00050 
00051 #define  AO2_MAGIC   0xa570b123
00052 
00053 /*!
00054  * What an astobj2 object looks like: fixed-size private data
00055  * followed by variable-size user data.
00056  */
00057 struct astobj2 {
00058    struct __priv_data priv_data;
00059    void *user_data[0];
00060 };
00061 
00062 #ifdef AST_DEVMODE
00063 #define AO2_DEBUG 1
00064 #endif
00065 
00066 #ifdef AO2_DEBUG
00067 struct ao2_stats {
00068    volatile int total_objects;
00069    volatile int total_mem;
00070    volatile int total_containers;
00071    volatile int total_refs;
00072    volatile int total_locked;
00073 };
00074 
00075 static struct ao2_stats ao2;
00076 #endif
00077 
00078 #ifndef HAVE_BKTR /* backtrace support */
00079 void ao2_bt(void) {}
00080 #else
00081 #include <execinfo.h>    /* for backtrace */
00082 
00083 void ao2_bt(void)
00084 {
00085    int c, i;
00086 #define N1  20
00087    void *addresses[N1];
00088    char **strings;
00089 
00090    c = backtrace(addresses, N1);
00091    strings = ast_bt_get_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 }
00098 #endif
00099 
00100 /*!
00101  * \brief convert from a pointer _p to a user-defined object
00102  *
00103  * \return the pointer to the astobj2 structure
00104  */
00105 static inline struct astobj2 *INTERNAL_OBJ(void *user_data)
00106 {
00107    struct astobj2 *p;
00108 
00109    if (!user_data) {
00110       ast_log(LOG_ERROR, "user_data is NULL\n");
00111       return NULL;
00112    }
00113 
00114    p = (struct astobj2 *) ((char *) user_data - sizeof(*p));
00115    if (AO2_MAGIC != (p->priv_data.magic) ) {
00116       ast_log(LOG_ERROR, "bad magic number 0x%x for %p\n", p->priv_data.magic, p);
00117       p = NULL;
00118    }
00119 
00120    return p;
00121 }
00122 
00123 enum ao2_callback_type {
00124    DEFAULT,
00125    WITH_DATA,
00126 };
00127 
00128 /*!
00129  * \brief convert from a pointer _p to an astobj2 object
00130  *
00131  * \return the pointer to the user-defined portion.
00132  */
00133 #define EXTERNAL_OBJ(_p)   ((_p) == NULL ? NULL : (_p)->user_data)
00134 
00135 /* the underlying functions common to debug and non-debug versions */
00136 
00137 static int __ao2_ref(void *user_data, const int delta);
00138 static struct ao2_container *__ao2_container_alloc(struct ao2_container *c, const uint n_buckets, ao2_hash_fn *hash_fn,
00139                                  ao2_callback_fn *cmp_fn);
00140 static struct bucket_list *__ao2_link(struct ao2_container *c, void *user_data, const char *file, int line, const char *func);
00141 static void *__ao2_callback(struct ao2_container *c,
00142    const enum search_flags flags, void *cb_fn, void *arg, void *data, enum ao2_callback_type type,
00143                 char *tag, char *file, int line, const char *funcname);
00144 static void * __ao2_iterator_next(struct ao2_iterator *a, struct bucket_list **q);
00145 
00146 #ifdef DEBUG_THREADS
00147 /* Need to override the macros defined in astobj2.h */
00148 #undef ao2_lock
00149 #undef ao2_trylock
00150 #undef ao2_unlock
00151 #endif
00152 
00153 int ao2_lock(void *user_data)
00154 {
00155    struct astobj2 *p = INTERNAL_OBJ(user_data);
00156 
00157    if (p == NULL)
00158       return -1;
00159 
00160 #ifdef AO2_DEBUG
00161    ast_atomic_fetchadd_int(&ao2.total_locked, 1);
00162 #endif
00163 
00164    return ast_mutex_lock(&p->priv_data.lock);
00165 }
00166 
00167 int _ao2_lock(void *user_data, const char *file, const char *func, int line, const char *var)
00168 {
00169    struct astobj2 *p = INTERNAL_OBJ(user_data);
00170 
00171    if (p == NULL)
00172       return -1;
00173 
00174 #ifdef AO2_DEBUG
00175    ast_atomic_fetchadd_int(&ao2.total_locked, 1);
00176 #endif
00177 
00178 #ifndef DEBUG_THREADS
00179    return ast_mutex_lock(&p->priv_data.lock);
00180 #else
00181    return __ast_pthread_mutex_lock(file, line, func, var, &p->priv_data.lock);
00182 #endif
00183 }
00184 
00185 int ao2_unlock(void *user_data)
00186 {
00187    struct astobj2 *p = INTERNAL_OBJ(user_data);
00188 
00189    if (p == NULL)
00190       return -1;
00191 
00192 #ifdef AO2_DEBUG
00193    ast_atomic_fetchadd_int(&ao2.total_locked, -1);
00194 #endif
00195 
00196    return ast_mutex_unlock(&p->priv_data.lock);
00197 }
00198 
00199 int _ao2_unlock(void *user_data, const char *file, const char *func, int line, const char *var)
00200 {
00201    struct astobj2 *p = INTERNAL_OBJ(user_data);
00202 
00203    if (p == NULL)
00204       return -1;
00205 
00206 #ifdef AO2_DEBUG
00207    ast_atomic_fetchadd_int(&ao2.total_locked, -1);
00208 #endif
00209 
00210 #ifndef DEBUG_THREADS
00211    return ast_mutex_unlock(&p->priv_data.lock);
00212 #else
00213    return __ast_pthread_mutex_unlock(file, line, func, var, &p->priv_data.lock);
00214 #endif
00215 }
00216 
00217 int ao2_trylock(void *user_data)
00218 {
00219    struct astobj2 *p = INTERNAL_OBJ(user_data);
00220    int ret;
00221    
00222    if (p == NULL)
00223       return -1;
00224    ret = ast_mutex_trylock(&p->priv_data.lock);
00225 
00226 #ifdef AO2_DEBUG
00227    if (!ret)
00228       ast_atomic_fetchadd_int(&ao2.total_locked, 1);
00229 #endif
00230    return ret;
00231 }
00232 
00233 int _ao2_trylock(void *user_data, const char *file, const char *func, int line, const char *var)
00234 {
00235    struct astobj2 *p = INTERNAL_OBJ(user_data);
00236    int ret;
00237    
00238    if (p == NULL)
00239       return -1;
00240 #ifndef DEBUG_THREADS
00241    ret = ast_mutex_trylock(&p->priv_data.lock);
00242 #else
00243    ret = __ast_pthread_mutex_trylock(file, line, func, var, &p->priv_data.lock);
00244 #endif
00245 
00246 #ifdef AO2_DEBUG
00247    if (!ret)
00248       ast_atomic_fetchadd_int(&ao2.total_locked, 1);
00249 #endif
00250    return ret;
00251 }
00252 
00253 void *ao2_object_get_lockaddr(void *obj)
00254 {
00255    struct astobj2 *p = INTERNAL_OBJ(obj);
00256    
00257    if (p == NULL)
00258       return NULL;
00259 
00260    return &p->priv_data.lock;
00261 }
00262 
00263 /*
00264  * The argument is a pointer to the user portion.
00265  */
00266 
00267 
00268 int _ao2_ref_debug(void *user_data, const int delta, char *tag, char *file, int line, const char *funcname)
00269 {
00270    struct astobj2 *obj = INTERNAL_OBJ(user_data);
00271    
00272    if (obj == NULL)
00273       return -1;
00274 
00275    if (delta != 0) {
00276       FILE *refo = fopen(REF_FILE,"a");
00277       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);
00278       fclose(refo);
00279    }
00280    if (obj->priv_data.ref_counter + delta == 0 && obj->priv_data.destructor_fn != NULL) { /* this isn't protected with lock; just for o/p */
00281          FILE *refo = fopen(REF_FILE,"a");    
00282          fprintf(refo, "%p **call destructor** %s:%d:%s (%s)\n", user_data, file, line, funcname, tag);   
00283          fclose(refo);
00284    }
00285    return __ao2_ref(user_data, delta);
00286 }
00287 
00288 int _ao2_ref(void *user_data, const int delta)
00289 {
00290    struct astobj2 *obj = INTERNAL_OBJ(user_data);
00291 
00292    if (obj == NULL)
00293       return -1;
00294 
00295    return __ao2_ref(user_data, delta);
00296 }
00297 
00298 static int __ao2_ref(void *user_data, const int delta)
00299 {
00300    struct astobj2 *obj = INTERNAL_OBJ(user_data);
00301    int current_value;
00302    int ret;
00303 
00304    if (obj == NULL)
00305       return -1;
00306 
00307    /* if delta is 0, just return the refcount */
00308    if (delta == 0)
00309       return (obj->priv_data.ref_counter);
00310 
00311    /* we modify with an atomic operation the reference counter */
00312    ret = ast_atomic_fetchadd_int(&obj->priv_data.ref_counter, delta);
00313    current_value = ret + delta;
00314 
00315 #ifdef AO2_DEBUG  
00316    ast_atomic_fetchadd_int(&ao2.total_refs, delta);
00317 #endif
00318 
00319    /* this case must never happen */
00320    if (current_value < 0)
00321       ast_log(LOG_ERROR, "refcount %d on object %p\n", current_value, user_data);
00322 
00323    if (current_value <= 0) { /* last reference, destroy the object */
00324       if (obj->priv_data.destructor_fn != NULL) {
00325          obj->priv_data.destructor_fn(user_data);
00326       }
00327 
00328       ast_mutex_destroy(&obj->priv_data.lock);
00329 #ifdef AO2_DEBUG
00330       ast_atomic_fetchadd_int(&ao2.total_mem, - obj->priv_data.data_size);
00331       ast_atomic_fetchadd_int(&ao2.total_objects, -1);
00332 #endif
00333       /* for safety, zero-out the astobj2 header and also the
00334        * first word of the user-data, which we make sure is always
00335        * allocated. */
00336       memset(obj, '\0', sizeof(struct astobj2 *) + sizeof(void *) );
00337       free(obj);
00338    }
00339 
00340    return ret;
00341 }
00342 
00343 /*
00344  * We always alloc at least the size of a void *,
00345  * for debugging purposes.
00346  */
00347 static void *__ao2_alloc(size_t data_size, ao2_destructor_fn destructor_fn, const char *file, int line, const char *funcname)
00348 {
00349    /* allocation */
00350    struct astobj2 *obj;
00351 
00352    if (data_size < sizeof(void *))
00353       data_size = sizeof(void *);
00354 
00355 #if defined(__AST_DEBUG_MALLOC)
00356    obj = __ast_calloc(1, sizeof(*obj) + data_size, file, line, funcname);
00357 #else
00358    obj = ast_calloc(1, sizeof(*obj) + data_size);
00359 #endif
00360 
00361    if (obj == NULL)
00362       return NULL;
00363 
00364    ast_mutex_init(&obj->priv_data.lock);
00365    obj->priv_data.magic = AO2_MAGIC;
00366    obj->priv_data.data_size = data_size;
00367    obj->priv_data.ref_counter = 1;
00368    obj->priv_data.destructor_fn = destructor_fn;   /* can be NULL */
00369 
00370 #ifdef AO2_DEBUG
00371    ast_atomic_fetchadd_int(&ao2.total_objects, 1);
00372    ast_atomic_fetchadd_int(&ao2.total_mem, data_size);
00373    ast_atomic_fetchadd_int(&ao2.total_refs, 1);
00374 #endif
00375 
00376    /* return a pointer to the user data */
00377    return EXTERNAL_OBJ(obj);
00378 }
00379 
00380 void *_ao2_alloc_debug(size_t data_size, ao2_destructor_fn destructor_fn, char *tag,
00381              const char *file, int line, const char *funcname, int ref_debug)
00382 {
00383    /* allocation */
00384    void *obj;
00385    FILE *refo = ref_debug ? fopen(REF_FILE,"a") : NULL;
00386 
00387    obj = __ao2_alloc(data_size, destructor_fn, file, line, funcname);
00388 
00389    if (obj == NULL)
00390       return NULL;
00391    
00392    if (refo) {
00393       fprintf(refo, "%p =1   %s:%d:%s (%s)\n", obj, file, line, funcname, tag);
00394       fclose(refo);
00395    }
00396 
00397    /* return a pointer to the user data */
00398    return obj;
00399 }
00400 
00401 void *_ao2_alloc(size_t data_size, ao2_destructor_fn destructor_fn)
00402 {
00403    return __ao2_alloc(data_size, destructor_fn, __FILE__, __LINE__, __FUNCTION__);
00404 }
00405 
00406 
00407 /* internal callback to destroy a container. */
00408 static void container_destruct(void *c);
00409 
00410 /* internal callback to destroy a container. */
00411 static void container_destruct_debug(void *c);
00412 
00413 /* each bucket in the container is a tailq. */
00414 AST_LIST_HEAD_NOLOCK(bucket, bucket_list);
00415 
00416 /*!
00417  * A container; stores the hash and callback functions, information on
00418  * the size, the hash bucket heads, and a version number, starting at 0
00419  * (for a newly created, empty container)
00420  * and incremented every time an object is inserted or deleted.
00421  * The assumption is that an object is never moved in a container,
00422  * but removed and readded with the new number.
00423  * The version number is especially useful when implementing iterators.
00424  * In fact, we can associate a unique, monotonically increasing number to
00425  * each object, which means that, within an iterator, we can store the
00426  * version number of the current object, and easily look for the next one,
00427  * which is the next one in the list with a higher number.
00428  * Since all objects have a version >0, we can use 0 as a marker for
00429  * 'we need the first object in the bucket'.
00430  *
00431  * \todo Linking and unlink objects is typically expensive, as it
00432  * involves a malloc() of a small object which is very inefficient.
00433  * To optimize this, we allocate larger arrays of bucket_list's
00434  * when we run out of them, and then manage our own freelist.
00435  * This will be more efficient as we can do the freelist management while
00436  * we hold the lock (that we need anyways).
00437  */
00438 struct ao2_container {
00439    ao2_hash_fn *hash_fn;
00440    ao2_callback_fn *cmp_fn;
00441    int n_buckets;
00442    /*! Number of elements in the container */
00443    int elements;
00444    /*! described above */
00445    int version;
00446    /*! variable size */
00447    struct bucket buckets[0];
00448 };
00449  
00450 /*!
00451  * \brief always zero hash function
00452  *
00453  * it is convenient to have a hash function that always returns 0.
00454  * This is basically used when we want to have a container that is
00455  * a simple linked list.
00456  *
00457  * \returns 0
00458  */
00459 static int hash_zero(const void *user_obj, const int flags)
00460 {
00461    return 0;
00462 }
00463 
00464 /*
00465  * A container is just an object, after all!
00466  */
00467 static struct ao2_container *__ao2_container_alloc(struct ao2_container *c, const unsigned int n_buckets, ao2_hash_fn *hash_fn,
00468                                  ao2_callback_fn *cmp_fn)
00469 {
00470    /* XXX maybe consistency check on arguments ? */
00471    /* compute the container size */
00472 
00473    if (!c)
00474       return NULL;
00475    
00476    c->version = 1;   /* 0 is a reserved value here */
00477    c->n_buckets = n_buckets;
00478    c->hash_fn = hash_fn ? hash_fn : hash_zero;
00479    c->cmp_fn = cmp_fn;
00480 
00481 #ifdef AO2_DEBUG
00482    ast_atomic_fetchadd_int(&ao2.total_containers, 1);
00483 #endif
00484 
00485    return c;
00486 }
00487 
00488 struct ao2_container *_ao2_container_alloc_debug(const unsigned int n_buckets, ao2_hash_fn *hash_fn,
00489                     ao2_callback_fn *cmp_fn, char *tag, char *file, int line,
00490                     const char *funcname, int ref_debug)
00491 {
00492    /* XXX maybe consistency check on arguments ? */
00493    /* compute the container size */
00494    size_t container_size = sizeof(struct ao2_container) + n_buckets * sizeof(struct bucket);
00495    struct ao2_container *c = _ao2_alloc_debug(container_size, container_destruct_debug, tag, file, line, funcname, ref_debug);
00496 
00497    return __ao2_container_alloc(c, n_buckets, hash_fn, cmp_fn);
00498 }
00499 
00500 struct ao2_container *
00501 _ao2_container_alloc(const unsigned int n_buckets, ao2_hash_fn *hash_fn,
00502       ao2_callback_fn *cmp_fn)
00503 {
00504    /* XXX maybe consistency check on arguments ? */
00505    /* compute the container size */
00506 
00507    size_t container_size = sizeof(struct ao2_container) + n_buckets * sizeof(struct bucket);
00508    struct ao2_container *c = _ao2_alloc(container_size, container_destruct);
00509 
00510    return __ao2_container_alloc(c, n_buckets, hash_fn, cmp_fn);
00511 }
00512 
00513 /*!
00514  * return the number of elements in the container
00515  */
00516 int ao2_container_count(struct ao2_container *c)
00517 {
00518    return c->elements;
00519 }
00520 
00521 /*!
00522  * A structure to create a linked list of entries,
00523  * used within a bucket.
00524  * XXX \todo this should be private to the container code
00525  */
00526 struct bucket_list {
00527    AST_LIST_ENTRY(bucket_list) entry;
00528    int version;
00529    struct astobj2 *astobj;    /* pointer to internal data */
00530 }; 
00531 
00532 /*
00533  * link an object to a container
00534  */
00535 
00536 static struct bucket_list *__ao2_link(struct ao2_container *c, void *user_data, const char *file, int line, const char *func)
00537 {
00538    int i;
00539    /* create a new list entry */
00540    struct bucket_list *p;
00541    struct astobj2 *obj = INTERNAL_OBJ(user_data);
00542 
00543    if (obj == NULL)
00544       return NULL;
00545 
00546    if (INTERNAL_OBJ(c) == NULL)
00547       return NULL;
00548 
00549    p = ast_calloc(1, sizeof(*p));
00550    if (!p)
00551       return NULL;
00552 
00553    i = abs(c->hash_fn(user_data, OBJ_POINTER));
00554 
00555    ao2_lock(c);
00556    i %= c->n_buckets;
00557    p->astobj = obj;
00558    p->version = ast_atomic_fetchadd_int(&c->version, 1);
00559    AST_LIST_INSERT_TAIL(&c->buckets[i], p, entry);
00560    ast_atomic_fetchadd_int(&c->elements, 1);
00561 
00562    /* the last two operations (ao2_ref, ao2_unlock) must be done by the calling func */
00563    return p;
00564 }
00565 
00566 void *_ao2_link_debug(struct ao2_container *c, void *user_data, char *tag, char *file, int line, const char *funcname)
00567 {
00568    struct bucket_list *p = __ao2_link(c, user_data, file, line, funcname);
00569 
00570    if (p) {
00571       _ao2_ref_debug(user_data, +1, tag, file, line, funcname);
00572       ao2_unlock(c);
00573    }
00574    return p;
00575 }
00576 
00577 void *_ao2_link(struct ao2_container *c, void *user_data)
00578 {
00579    struct bucket_list *p = __ao2_link(c, user_data, __FILE__, __LINE__, __PRETTY_FUNCTION__);
00580 
00581    if (p) {
00582       _ao2_ref(user_data, +1);
00583       ao2_unlock(c);
00584    }
00585    return p;
00586 }
00587 
00588 /*!
00589  * \brief another convenience function is a callback that matches on address
00590  */
00591 int ao2_match_by_addr(void *user_data, void *arg, int flags)
00592 {
00593    return (user_data == arg) ? (CMP_MATCH | CMP_STOP) : 0;
00594 }
00595 
00596 /*
00597  * Unlink an object from the container
00598  * and destroy the associated * ao2_bucket_list structure.
00599  */
00600 void *_ao2_unlink_debug(struct ao2_container *c, void *user_data, char *tag,
00601                   char *file, int line, const char *funcname)
00602 {
00603    if (INTERNAL_OBJ(user_data) == NULL)   /* safety check on the argument */
00604       return NULL;
00605 
00606    _ao2_callback_debug(c, OBJ_UNLINK | OBJ_POINTER | OBJ_NODATA, ao2_match_by_addr, user_data, tag, file, line, funcname);
00607 
00608    return NULL;
00609 }
00610 
00611 void *_ao2_unlink(struct ao2_container *c, void *user_data)
00612 {
00613    if (INTERNAL_OBJ(user_data) == NULL)   /* safety check on the argument */
00614       return NULL;
00615 
00616    _ao2_callback(c, OBJ_UNLINK | OBJ_POINTER | OBJ_NODATA, ao2_match_by_addr, user_data);
00617 
00618    return NULL;
00619 }
00620 
00621 /*! 
00622  * \brief special callback that matches all 
00623  */ 
00624 static int cb_true(void *user_data, void *arg, int flags)
00625 {
00626    return CMP_MATCH;
00627 }
00628 
00629 /*!
00630  * \brief similar to cb_true, but is an ao2_callback_data_fn instead
00631  */
00632 static int cb_true_data(void *user_data, void *arg, void *data, int flags)
00633 {
00634    return CMP_MATCH;
00635 }
00636 
00637 /*!
00638  * Browse the container using different stategies accoding the flags.
00639  * \return Is a pointer to an object or to a list of object if OBJ_MULTIPLE is 
00640  * specified.
00641  * Luckily, for debug purposes, the added args (tag, file, line, funcname)
00642  * aren't an excessive load to the system, as the callback should not be
00643  * called as often as, say, the ao2_ref func is called.
00644  */
00645 static void *__ao2_callback(struct ao2_container *c,
00646    const enum search_flags flags, void *cb_fn, void *arg, void *data, enum ao2_callback_type type,
00647    char *tag, char *file, int line, const char *funcname)
00648 {
00649    int i, start, last;  /* search boundaries */
00650    void *ret = NULL;
00651    ao2_callback_fn *cb_default = NULL;
00652    ao2_callback_data_fn *cb_withdata = NULL;
00653 
00654    if (INTERNAL_OBJ(c) == NULL)  /* safety check on the argument */
00655       return NULL;
00656 
00657    if ((flags & (OBJ_MULTIPLE | OBJ_NODATA)) == OBJ_MULTIPLE) {
00658       ast_log(LOG_WARNING, "multiple data return not implemented yet (flags %x)\n", flags);
00659       return NULL;
00660    }
00661 
00662    /* override the match function if necessary */
00663    if (cb_fn == NULL) { /* if NULL, match everything */
00664       if (type == WITH_DATA) {
00665          cb_withdata = cb_true_data;
00666       } else {
00667          cb_default = cb_true;
00668       }
00669    } else {
00670       /* We do this here to avoid the per object casting penalty (even though
00671          that is probably optimized away anyway. */
00672       if (type == WITH_DATA) {
00673          cb_withdata = cb_fn;
00674       } else {
00675          cb_default = cb_fn;
00676       }
00677    }
00678 
00679    /*
00680     * XXX this can be optimized.
00681     * If we have a hash function and lookup by pointer,
00682     * run the hash function. Otherwise, scan the whole container
00683     * (this only for the time being. We need to optimize this.)
00684     */
00685    if ((flags & OBJ_POINTER)) /* we know hash can handle this case */
00686       start = i = c->hash_fn(arg, flags & OBJ_POINTER) % c->n_buckets;
00687    else        /* don't know, let's scan all buckets */
00688       start = i = -1;      /* XXX this must be fixed later. */
00689 
00690    /* determine the search boundaries: i..last-1 */
00691    if (i < 0) {
00692       start = i = 0;
00693       last = c->n_buckets;
00694    } else if ((flags & OBJ_CONTINUE)) {
00695       last = c->n_buckets;
00696    } else {
00697       last = i + 1;
00698    }
00699 
00700    ao2_lock(c);   /* avoid modifications to the content */
00701 
00702    for (; i < last ; i++) {
00703       /* scan the list with prev-cur pointers */
00704       struct bucket_list *cur;
00705 
00706       AST_LIST_TRAVERSE_SAFE_BEGIN(&c->buckets[i], cur, entry) {
00707          int match = (CMP_MATCH | CMP_STOP);
00708 
00709          if (type == WITH_DATA) {
00710             match &= cb_withdata(EXTERNAL_OBJ(cur->astobj), arg, data, flags);
00711          } else {
00712             match &= cb_default(EXTERNAL_OBJ(cur->astobj), arg, flags);
00713          }
00714 
00715          /* we found the object, performing operations according flags */
00716          if (match == 0) { /* no match, no stop, continue */
00717             continue;
00718          } else if (match == CMP_STOP) {  /* no match but stop, we are done */
00719             i = last;
00720             break;
00721          }
00722          /* we have a match (CMP_MATCH) here */
00723          if (!(flags & OBJ_NODATA)) {  /* if must return the object, record the value */
00724             /* it is important to handle this case before the unlink */
00725             ret = EXTERNAL_OBJ(cur->astobj);
00726             if (tag)
00727                _ao2_ref_debug(ret, 1, tag, file, line, funcname);
00728             else
00729                _ao2_ref(ret, 1);
00730          }
00731 
00732          if (flags & OBJ_UNLINK) {  /* must unlink */
00733             struct bucket_list *x = cur;
00734 
00735             /* we are going to modify the container, so update version */
00736             ast_atomic_fetchadd_int(&c->version, 1);
00737             AST_LIST_REMOVE_CURRENT(entry);
00738             /* update number of elements and version */
00739             ast_atomic_fetchadd_int(&c->elements, -1);
00740             if (tag)
00741                _ao2_ref_debug(EXTERNAL_OBJ(x->astobj), -1, tag, file, line, funcname);
00742             else
00743                _ao2_ref(EXTERNAL_OBJ(x->astobj), -1);
00744             free(x); /* free the link record */
00745          }
00746 
00747          if ((match & CMP_STOP) || (flags & OBJ_MULTIPLE) == 0) {
00748             /* We found the only match we need */
00749             i = last;   /* force exit from outer loop */
00750             break;
00751          }
00752          if (!(flags & OBJ_NODATA)) {
00753 #if 0 /* XXX to be completed */
00754             /*
00755              * This is the multiple-return case. We need to link
00756              * the object in a list. The refcount is already increased.
00757              */
00758 #endif
00759          }
00760       }
00761       AST_LIST_TRAVERSE_SAFE_END;
00762 
00763       if (ret) {
00764          /* This assumes OBJ_MULTIPLE with !OBJ_NODATA is still not implemented */
00765          break;
00766       }
00767 
00768       if (i == c->n_buckets - 1 && (flags & OBJ_POINTER) && (flags & OBJ_CONTINUE)) {
00769          /* Move to the beginning to ensure we check every bucket */
00770          i = -1;
00771          last = start;
00772       }
00773    }
00774    ao2_unlock(c);
00775    return ret;
00776 }
00777 
00778 void *_ao2_callback_debug(struct ao2_container *c,
00779                    const enum search_flags flags,
00780                    ao2_callback_fn *cb_fn, void *arg,
00781                    char *tag, char *file, int line, const char *funcname)
00782 {
00783    return __ao2_callback(c,flags, cb_fn, arg, NULL, DEFAULT, tag, file, line, funcname);
00784 }
00785 
00786 void *_ao2_callback(struct ao2_container *c, const enum search_flags flags,
00787                     ao2_callback_fn *cb_fn, void *arg)
00788 {
00789    return __ao2_callback(c,flags, cb_fn, arg, NULL, DEFAULT, NULL, NULL, 0, NULL);
00790 }
00791 
00792 void *_ao2_callback_data_debug(struct ao2_container *c,
00793                    const enum search_flags flags,
00794                    ao2_callback_data_fn *cb_fn, void *arg, void *data,
00795                    char *tag, char *file, int line, const char *funcname)
00796 {
00797    return __ao2_callback(c, flags, cb_fn, arg, data, WITH_DATA, tag, file, line, funcname);
00798 }
00799 
00800 void *_ao2_callback_data(struct ao2_container *c, const enum search_flags flags,
00801                ao2_callback_data_fn *cb_fn, void *arg, void *data)
00802 {
00803    return __ao2_callback(c, flags, cb_fn, arg, data, WITH_DATA, NULL, NULL, 0, NULL);
00804 }
00805 
00806 /*!
00807  * the find function just invokes the default callback with some reasonable flags.
00808  */
00809 void *_ao2_find_debug(struct ao2_container *c, void *arg, enum search_flags flags, char *tag, char *file, int line, const char *funcname)
00810 {
00811    return _ao2_callback_debug(c, flags, c->cmp_fn, arg, tag, file, line, funcname);
00812 }
00813 
00814 void *_ao2_find(struct ao2_container *c, void *arg, enum search_flags flags)
00815 {
00816    return _ao2_callback(c, flags, c->cmp_fn, arg);
00817 }
00818 
00819 /*!
00820  * initialize an iterator so we start from the first object
00821  */
00822 struct ao2_iterator ao2_iterator_init(struct ao2_container *c, int flags)
00823 {
00824    struct ao2_iterator a = {
00825       .c = c,
00826       .flags = flags
00827    };
00828 
00829    ao2_ref(c, +1);
00830    
00831    return a;
00832 }
00833 
00834 /*!
00835  * destroy an iterator
00836  */
00837 void ao2_iterator_destroy(struct ao2_iterator *i)
00838 {
00839    ao2_ref(i->c, -1);
00840    i->c = NULL;
00841 }
00842 
00843 /*
00844  * move to the next element in the container.
00845  */
00846 static void * __ao2_iterator_next(struct ao2_iterator *a, struct bucket_list **q)
00847 {
00848    int lim;
00849    struct bucket_list *p = NULL;
00850    void *ret = NULL;
00851 
00852    *q = NULL;
00853    
00854    if (INTERNAL_OBJ(a->c) == NULL)
00855       return NULL;
00856 
00857    if (!(a->flags & AO2_ITERATOR_DONTLOCK))
00858       ao2_lock(a->c);
00859 
00860    /* optimization. If the container is unchanged and
00861     * we have a pointer, try follow it
00862     */
00863    if (a->c->version == a->c_version && (p = a->obj) ) {
00864       if ( (p = AST_LIST_NEXT(p, entry)) )
00865          goto found;
00866       /* nope, start from the next bucket */
00867       a->bucket++;
00868       a->version = 0;
00869       a->obj = NULL;
00870    }
00871 
00872    lim = a->c->n_buckets;
00873 
00874    /* Browse the buckets array, moving to the next
00875     * buckets if we don't find the entry in the current one.
00876     * Stop when we find an element with version number greater
00877     * than the current one (we reset the version to 0 when we
00878     * switch buckets).
00879     */
00880    for (; a->bucket < lim; a->bucket++, a->version = 0) {
00881       /* scan the current bucket */
00882       AST_LIST_TRAVERSE(&a->c->buckets[a->bucket], p, entry) {
00883          if (p->version > a->version)
00884             goto found;
00885       }
00886    }
00887 
00888 found:
00889    if (p) {
00890       a->version = p->version;
00891       a->obj = p;
00892       a->c_version = a->c->version;
00893       ret = EXTERNAL_OBJ(p->astobj);
00894       /* inc refcount of returned object */
00895       *q = p;
00896    }
00897 
00898    return ret;
00899 }
00900 
00901 void * _ao2_iterator_next_debug(struct ao2_iterator *a, char *tag, char *file, int line, const char *funcname)
00902 {
00903    struct bucket_list *p;
00904    void *ret = NULL;
00905 
00906    ret = __ao2_iterator_next(a, &p);
00907    
00908    if (p) {
00909       /* inc refcount of returned object */
00910       _ao2_ref_debug(ret, 1, tag, file, line, funcname);
00911    }
00912 
00913    if (!(a->flags & AO2_ITERATOR_DONTLOCK))
00914       ao2_unlock(a->c);
00915 
00916    return ret;
00917 }
00918 
00919 void * _ao2_iterator_next(struct ao2_iterator *a)
00920 {
00921    struct bucket_list *p = NULL;
00922    void *ret = NULL;
00923 
00924    ret = __ao2_iterator_next(a, &p);
00925    
00926    if (p) {
00927       /* inc refcount of returned object */
00928       _ao2_ref(ret, 1);
00929    }
00930 
00931    if (!(a->flags & AO2_ITERATOR_DONTLOCK))
00932       ao2_unlock(a->c);
00933 
00934    return ret;
00935 }
00936 
00937 /* callback for destroying container.
00938  * we can make it simple as we know what it does
00939  */
00940 static int cd_cb(void *obj, void *arg, int flag)
00941 {
00942    _ao2_ref(obj, -1);
00943    return 0;
00944 }
00945    
00946 static int cd_cb_debug(void *obj, void *arg, int flag)
00947 {
00948    _ao2_ref_debug(obj, -1, "deref object via container destroy",  __FILE__, __LINE__, __PRETTY_FUNCTION__);
00949    return 0;
00950 }
00951    
00952 static void container_destruct(void *_c)
00953 {
00954    struct ao2_container *c = _c;
00955    int i;
00956 
00957    _ao2_callback(c, OBJ_UNLINK, cd_cb, NULL);
00958 
00959    for (i = 0; i < c->n_buckets; i++) {
00960       struct bucket_list *current;
00961 
00962       while ((current = AST_LIST_REMOVE_HEAD(&c->buckets[i], entry))) {
00963          ast_free(current);
00964       }
00965    }
00966 
00967 #ifdef AO2_DEBUG
00968    ast_atomic_fetchadd_int(&ao2.total_containers, -1);
00969 #endif
00970 }
00971 
00972 static void container_destruct_debug(void *_c)
00973 {
00974    struct ao2_container *c = _c;
00975    int i;
00976 
00977    _ao2_callback_debug(c, OBJ_UNLINK, cd_cb_debug, NULL, "container_destruct_debug called", __FILE__, __LINE__, __PRETTY_FUNCTION__);
00978 
00979    for (i = 0; i < c->n_buckets; i++) {
00980       struct bucket_list *current;
00981 
00982       while ((current = AST_LIST_REMOVE_HEAD(&c->buckets[i], entry))) {
00983          ast_free(current);
00984       }
00985    }
00986 
00987 #ifdef AO2_DEBUG
00988    ast_atomic_fetchadd_int(&ao2.total_containers, -1);
00989 #endif
00990 }
00991 
00992 #ifdef AO2_DEBUG
00993 static int print_cb(void *obj, void *arg, int flag)
00994 {
00995    int *fd = arg;
00996    char *s = (char *)obj;
00997 
00998    ast_cli(*fd, "string <%s>\n", s);
00999    return 0;
01000 }
01001 
01002 /*
01003  * Print stats
01004  */
01005 static char *handle_astobj2_stats(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
01006 {
01007    switch (cmd) {
01008    case CLI_INIT:
01009       e->command = "astobj2 show stats";
01010       e->usage = "Usage: astobj2 show stats\n"
01011             "       Show astobj2 show stats\n";
01012       return NULL;
01013    case CLI_GENERATE:
01014       return NULL;
01015    }
01016    ast_cli(a->fd, "Objects    : %d\n", ao2.total_objects);
01017    ast_cli(a->fd, "Containers : %d\n", ao2.total_containers);
01018    ast_cli(a->fd, "Memory     : %d\n", ao2.total_mem);
01019    ast_cli(a->fd, "Locked     : %d\n", ao2.total_locked);
01020    ast_cli(a->fd, "Refs       : %d\n", ao2.total_refs);
01021    return CLI_SUCCESS;
01022 }
01023 
01024 /*
01025  * This is testing code for astobj
01026  */
01027 static char *handle_astobj2_test(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
01028 {
01029    struct ao2_container *c1;
01030    int i, lim;
01031    char *obj;
01032    static int prof_id = -1;
01033    struct ast_cli_args fake_args = { a->fd, 0, NULL };
01034 
01035    switch (cmd) {
01036    case CLI_INIT:
01037       e->command = "astobj2 test";
01038       e->usage = "Usage: astobj2 test <num>\n"
01039             "       Runs astobj2 test. Creates 'num' objects,\n"
01040             "       and test iterators, callbacks and may be other stuff\n";
01041       return NULL;
01042    case CLI_GENERATE:
01043       return NULL;
01044    }
01045 
01046    if (a->argc != 3) {
01047       return CLI_SHOWUSAGE;
01048    }
01049 
01050    if (prof_id == -1)
01051       prof_id = ast_add_profile("ao2_alloc", 0);
01052 
01053    ast_cli(a->fd, "argc %d argv %s %s %s\n", a->argc, a->argv[0], a->argv[1], a->argv[2]);
01054    lim = atoi(a->argv[2]);
01055    ast_cli(a->fd, "called astobj_test\n");
01056 
01057    handle_astobj2_stats(e, CLI_HANDLER, &fake_args);
01058    /*
01059     * allocate a container with no default callback, and no hash function.
01060     * No hash means everything goes in the same bucket.
01061     */
01062    c1 = ao2_t_container_alloc(100, NULL /* no callback */, NULL /* no hash */,"test");
01063    ast_cli(a->fd, "container allocated as %p\n", c1);
01064 
01065    /*
01066     * fill the container with objects.
01067     * ao2_alloc() gives us a reference which we pass to the
01068     * container when we do the insert.
01069     */
01070    for (i = 0; i < lim; i++) {
01071       ast_mark(prof_id, 1 /* start */);
01072       obj = ao2_t_alloc(80, NULL,"test");
01073       ast_mark(prof_id, 0 /* stop */);
01074       ast_cli(a->fd, "object %d allocated as %p\n", i, obj);
01075       sprintf(obj, "-- this is obj %d --", i);
01076       ao2_link(c1, obj);
01077       /* At this point, the refcount on obj is 2 due to the allocation
01078        * and linking. We can go ahead and reduce the refcount by 1
01079        * right here so that when the container is unreffed later, the
01080        * objects will be freed
01081        */
01082       ao2_t_ref(obj, -1, "test");
01083    }
01084    ast_cli(a->fd, "testing callbacks\n");
01085    ao2_t_callback(c1, 0, print_cb, &a->fd, "test callback");
01086    ast_cli(a->fd, "testing iterators, remove every second object\n");
01087    {
01088       struct ao2_iterator ai;
01089       int x = 0;
01090 
01091       ai = ao2_iterator_init(c1, 0);
01092       while ( (obj = ao2_t_iterator_next(&ai,"test")) ) {
01093          ast_cli(a->fd, "iterator on <%s>\n", obj);
01094          if (x++ & 1)
01095             ao2_t_unlink(c1, obj,"test");
01096          ao2_t_ref(obj, -1,"test");
01097       }
01098       ao2_iterator_destroy(&ai);
01099       ast_cli(a->fd, "testing iterators again\n");
01100       ai = ao2_iterator_init(c1, 0);
01101       while ( (obj = ao2_t_iterator_next(&ai,"test")) ) {
01102          ast_cli(a->fd, "iterator on <%s>\n", obj);
01103          ao2_t_ref(obj, -1,"test");
01104       }
01105       ao2_iterator_destroy(&ai);
01106    }
01107    ast_cli(a->fd, "testing callbacks again\n");
01108    ao2_t_callback(c1, 0, print_cb, &a->fd, "test callback");
01109 
01110    ast_verbose("now you should see an error message:\n");
01111    ao2_t_ref(&i, -1, "");  /* i is not a valid object so we print an error here */
01112 
01113    ast_cli(a->fd, "destroy container\n");
01114    ao2_t_ref(c1, -1, "");  /* destroy container */
01115    handle_astobj2_stats(e, CLI_HANDLER, &fake_args);
01116    return CLI_SUCCESS;
01117 }
01118 
01119 static struct ast_cli_entry cli_astobj2[] = {
01120    AST_CLI_DEFINE(handle_astobj2_stats, "Print astobj2 statistics"),
01121    AST_CLI_DEFINE(handle_astobj2_test, "Test astobj2"),
01122 };
01123 #endif /* AO2_DEBUG */
01124 
01125 int astobj2_init(void)
01126 {
01127 #ifdef AO2_DEBUG
01128    ast_cli_register_multiple(cli_astobj2, ARRAY_LEN(cli_astobj2));
01129 #endif
01130 
01131    return 0;
01132 }