Sat Mar 10 01:54:04 2012

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: 342487 $")
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 internal_ao2_ref(void *user_data, const int delta);
00138 static struct ao2_container *internal_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_entry *internal_ao2_link(struct ao2_container *c, void *user_data, const char *file, int line, const char *func);
00141 static void *internal_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 *internal_ao2_iterator_next(struct ao2_iterator *a, struct bucket_entry **q);
00145 
00146 int __ao2_lock(void *user_data, const char *file, const char *func, int line, const char *var)
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    return __ast_pthread_mutex_lock(file, line, func, var, &p->priv_data.lock);
00158 }
00159 
00160 int __ao2_unlock(void *user_data, const char *file, const char *func, int line, const char *var)
00161 {
00162    struct astobj2 *p = INTERNAL_OBJ(user_data);
00163 
00164    if (p == NULL)
00165       return -1;
00166 
00167 #ifdef AO2_DEBUG
00168    ast_atomic_fetchadd_int(&ao2.total_locked, -1);
00169 #endif
00170 
00171    return __ast_pthread_mutex_unlock(file, line, func, var, &p->priv_data.lock);
00172 }
00173 
00174 int __ao2_trylock(void *user_data, const char *file, const char *func, int line, const char *var)
00175 {
00176    struct astobj2 *p = INTERNAL_OBJ(user_data);
00177    int ret;
00178    
00179    if (p == NULL)
00180       return -1;
00181    ret = __ast_pthread_mutex_trylock(file, line, func, var, &p->priv_data.lock);
00182 
00183 #ifdef AO2_DEBUG
00184    if (!ret)
00185       ast_atomic_fetchadd_int(&ao2.total_locked, 1);
00186 #endif
00187    return ret;
00188 }
00189 
00190 void *ao2_object_get_lockaddr(void *obj)
00191 {
00192    struct astobj2 *p = INTERNAL_OBJ(obj);
00193    
00194    if (p == NULL)
00195       return NULL;
00196 
00197    return &p->priv_data.lock;
00198 }
00199 
00200 /*
00201  * The argument is a pointer to the user portion.
00202  */
00203 
00204 
00205 int __ao2_ref_debug(void *user_data, const int delta, char *tag, char *file, int line, const char *funcname)
00206 {
00207    struct astobj2 *obj = INTERNAL_OBJ(user_data);
00208    
00209    if (obj == NULL)
00210       return -1;
00211 
00212    if (delta != 0) {
00213       FILE *refo = fopen(REF_FILE, "a");
00214       if (refo) {
00215          fprintf(refo, "%p %s%d   %s:%d:%s (%s) [@%d]\n", user_data, (delta < 0 ? "" : "+"),
00216             delta, file, line, funcname, tag, obj ? obj->priv_data.ref_counter : -1);
00217          fclose(refo);
00218       }
00219    }
00220    if (obj->priv_data.ref_counter + delta == 0 && obj->priv_data.destructor_fn != NULL) { /* this isn't protected with lock; just for o/p */
00221       FILE *refo = fopen(REF_FILE, "a");
00222       if (refo) {
00223          fprintf(refo, "%p **call destructor** %s:%d:%s (%s)\n", user_data, file, line, funcname, tag);
00224          fclose(refo);
00225       }
00226    }
00227    return internal_ao2_ref(user_data, delta);
00228 }
00229 
00230 int __ao2_ref(void *user_data, const int delta)
00231 {
00232    struct astobj2 *obj = INTERNAL_OBJ(user_data);
00233 
00234    if (obj == NULL)
00235       return -1;
00236 
00237    return internal_ao2_ref(user_data, delta);
00238 }
00239 
00240 static int internal_ao2_ref(void *user_data, const int delta)
00241 {
00242    struct astobj2 *obj = INTERNAL_OBJ(user_data);
00243    int current_value;
00244    int ret;
00245 
00246    if (obj == NULL)
00247       return -1;
00248 
00249    /* if delta is 0, just return the refcount */
00250    if (delta == 0)
00251       return (obj->priv_data.ref_counter);
00252 
00253    /* we modify with an atomic operation the reference counter */
00254    ret = ast_atomic_fetchadd_int(&obj->priv_data.ref_counter, delta);
00255    current_value = ret + delta;
00256 
00257 #ifdef AO2_DEBUG  
00258    ast_atomic_fetchadd_int(&ao2.total_refs, delta);
00259 #endif
00260 
00261    /* this case must never happen */
00262    if (current_value < 0)
00263       ast_log(LOG_ERROR, "refcount %d on object %p\n", current_value, user_data);
00264 
00265    if (current_value <= 0) { /* last reference, destroy the object */
00266       if (obj->priv_data.destructor_fn != NULL) {
00267          obj->priv_data.destructor_fn(user_data);
00268       }
00269 
00270       ast_mutex_destroy(&obj->priv_data.lock);
00271 #ifdef AO2_DEBUG
00272       ast_atomic_fetchadd_int(&ao2.total_mem, - obj->priv_data.data_size);
00273       ast_atomic_fetchadd_int(&ao2.total_objects, -1);
00274 #endif
00275       /* for safety, zero-out the astobj2 header and also the
00276        * first word of the user-data, which we make sure is always
00277        * allocated. */
00278       memset(obj, '\0', sizeof(struct astobj2 *) + sizeof(void *) );
00279       ast_free(obj);
00280    }
00281 
00282    return ret;
00283 }
00284 
00285 /*
00286  * We always alloc at least the size of a void *,
00287  * for debugging purposes.
00288  */
00289 static void *internal_ao2_alloc(size_t data_size, ao2_destructor_fn destructor_fn, const char *file, int line, const char *funcname)
00290 {
00291    /* allocation */
00292    struct astobj2 *obj;
00293 
00294    if (data_size < sizeof(void *))
00295       data_size = sizeof(void *);
00296 
00297 #if defined(__AST_DEBUG_MALLOC)
00298    obj = __ast_calloc(1, sizeof(*obj) + data_size, file, line, funcname);
00299 #else
00300    obj = ast_calloc(1, sizeof(*obj) + data_size);
00301 #endif
00302 
00303    if (obj == NULL)
00304       return NULL;
00305 
00306    ast_mutex_init(&obj->priv_data.lock);
00307    obj->priv_data.magic = AO2_MAGIC;
00308    obj->priv_data.data_size = data_size;
00309    obj->priv_data.ref_counter = 1;
00310    obj->priv_data.destructor_fn = destructor_fn;   /* can be NULL */
00311 
00312 #ifdef AO2_DEBUG
00313    ast_atomic_fetchadd_int(&ao2.total_objects, 1);
00314    ast_atomic_fetchadd_int(&ao2.total_mem, data_size);
00315    ast_atomic_fetchadd_int(&ao2.total_refs, 1);
00316 #endif
00317 
00318    /* return a pointer to the user data */
00319    return EXTERNAL_OBJ(obj);
00320 }
00321 
00322 void *__ao2_alloc_debug(size_t data_size, ao2_destructor_fn destructor_fn, char *tag,
00323          const char *file, int line, const char *funcname, int ref_debug)
00324 {
00325    /* allocation */
00326    void *obj;
00327    FILE *refo;
00328 
00329    if ((obj = internal_ao2_alloc(data_size, destructor_fn, file, line, funcname)) == NULL) {
00330       return NULL;
00331    }
00332 
00333    if (ref_debug && (refo = fopen(REF_FILE, "a"))) {
00334       fprintf(refo, "%p =1   %s:%d:%s (%s)\n", obj, file, line, funcname, tag);
00335       fclose(refo);
00336    }
00337 
00338    /* return a pointer to the user data */
00339    return obj;
00340 }
00341 
00342 void *__ao2_alloc(size_t data_size, ao2_destructor_fn destructor_fn)
00343 {
00344    return internal_ao2_alloc(data_size, destructor_fn, __FILE__, __LINE__, __FUNCTION__);
00345 }
00346 
00347 
00348 /* internal callback to destroy a container. */
00349 static void container_destruct(void *c);
00350 
00351 /* internal callback to destroy a container. */
00352 static void container_destruct_debug(void *c);
00353 
00354 /* each bucket in the container is a tailq. */
00355 AST_LIST_HEAD_NOLOCK(bucket, bucket_entry);
00356 
00357 /*!
00358  * A container; stores the hash and callback functions, information on
00359  * the size, the hash bucket heads, and a version number, starting at 0
00360  * (for a newly created, empty container)
00361  * and incremented every time an object is inserted or deleted.
00362  * The assumption is that an object is never moved in a container,
00363  * but removed and readded with the new number.
00364  * The version number is especially useful when implementing iterators.
00365  * In fact, we can associate a unique, monotonically increasing number to
00366  * each object, which means that, within an iterator, we can store the
00367  * version number of the current object, and easily look for the next one,
00368  * which is the next one in the list with a higher number.
00369  * Since all objects have a version >0, we can use 0 as a marker for
00370  * 'we need the first object in the bucket'.
00371  *
00372  * \todo Linking and unlink objects is typically expensive, as it
00373  * involves a malloc() of a small object which is very inefficient.
00374  * To optimize this, we allocate larger arrays of bucket_entry's
00375  * when we run out of them, and then manage our own freelist.
00376  * This will be more efficient as we can do the freelist management while
00377  * we hold the lock (that we need anyways).
00378  */
00379 struct ao2_container {
00380    ao2_hash_fn *hash_fn;
00381    ao2_callback_fn *cmp_fn;
00382    int n_buckets;
00383    /*! Number of elements in the container */
00384    int elements;
00385    /*! described above */
00386    int version;
00387    /*! variable size */
00388    struct bucket buckets[0];
00389 };
00390  
00391 /*!
00392  * \brief always zero hash function
00393  *
00394  * it is convenient to have a hash function that always returns 0.
00395  * This is basically used when we want to have a container that is
00396  * a simple linked list.
00397  *
00398  * \returns 0
00399  */
00400 static int hash_zero(const void *user_obj, const int flags)
00401 {
00402    return 0;
00403 }
00404 
00405 /*
00406  * A container is just an object, after all!
00407  */
00408 static struct ao2_container *internal_ao2_container_alloc(struct ao2_container *c, const unsigned int n_buckets, ao2_hash_fn *hash_fn,
00409                        ao2_callback_fn *cmp_fn)
00410 {
00411    /* XXX maybe consistency check on arguments ? */
00412    /* compute the container size */
00413 
00414    if (!c)
00415       return NULL;
00416    
00417    c->version = 1;   /* 0 is a reserved value here */
00418    c->n_buckets = hash_fn ? n_buckets : 1;
00419    c->hash_fn = hash_fn ? hash_fn : hash_zero;
00420    c->cmp_fn = cmp_fn;
00421 
00422 #ifdef AO2_DEBUG
00423    ast_atomic_fetchadd_int(&ao2.total_containers, 1);
00424 #endif
00425 
00426    return c;
00427 }
00428 
00429 struct ao2_container *__ao2_container_alloc_debug(const unsigned int n_buckets, ao2_hash_fn *hash_fn,
00430                     ao2_callback_fn *cmp_fn, char *tag, char *file, int line,
00431                     const char *funcname, int ref_debug)
00432 {
00433    /* XXX maybe consistency check on arguments ? */
00434    /* compute the container size */
00435    const unsigned int num_buckets = hash_fn ? n_buckets : 1;
00436    size_t container_size = sizeof(struct ao2_container) + num_buckets * sizeof(struct bucket);
00437    struct ao2_container *c = __ao2_alloc_debug(container_size, container_destruct_debug, tag, file, line, funcname, ref_debug);
00438 
00439    return internal_ao2_container_alloc(c, num_buckets, hash_fn, cmp_fn);
00440 }
00441 
00442 struct ao2_container *__ao2_container_alloc(const unsigned int n_buckets, ao2_hash_fn *hash_fn,
00443                    ao2_callback_fn *cmp_fn)
00444 {
00445    /* XXX maybe consistency check on arguments ? */
00446    /* compute the container size */
00447 
00448    const unsigned int num_buckets = hash_fn ? n_buckets : 1;
00449    size_t container_size = sizeof(struct ao2_container) + num_buckets * sizeof(struct bucket);
00450    struct ao2_container *c = __ao2_alloc(container_size, container_destruct);
00451 
00452    return internal_ao2_container_alloc(c, num_buckets, hash_fn, cmp_fn);
00453 }
00454 
00455 /*!
00456  * return the number of elements in the container
00457  */
00458 int ao2_container_count(struct ao2_container *c)
00459 {
00460    return c->elements;
00461 }
00462 
00463 /*!
00464  * A structure to create a linked list of entries,
00465  * used within a bucket.
00466  * XXX \todo this should be private to the container code
00467  */
00468 struct bucket_entry {
00469    AST_LIST_ENTRY(bucket_entry) entry;
00470    int version;
00471    struct astobj2 *astobj;    /* pointer to internal data */
00472 }; 
00473 
00474 /*
00475  * link an object to a container
00476  */
00477 
00478 static struct bucket_entry *internal_ao2_link(struct ao2_container *c, void *user_data, const char *file, int line, const char *func)
00479 {
00480    int i;
00481    /* create a new list entry */
00482    struct bucket_entry *p;
00483    struct astobj2 *obj = INTERNAL_OBJ(user_data);
00484 
00485    if (obj == NULL)
00486       return NULL;
00487 
00488    if (INTERNAL_OBJ(c) == NULL)
00489       return NULL;
00490 
00491    p = ast_calloc(1, sizeof(*p));
00492    if (!p)
00493       return NULL;
00494 
00495    i = abs(c->hash_fn(user_data, OBJ_POINTER));
00496 
00497    ao2_lock(c);
00498    i %= c->n_buckets;
00499    p->astobj = obj;
00500    p->version = ast_atomic_fetchadd_int(&c->version, 1);
00501    AST_LIST_INSERT_TAIL(&c->buckets[i], p, entry);
00502    ast_atomic_fetchadd_int(&c->elements, 1);
00503 
00504    /* the last two operations (ao2_ref, ao2_unlock) must be done by the calling func */
00505    return p;
00506 }
00507 
00508 void *__ao2_link_debug(struct ao2_container *c, void *user_data, char *tag, char *file, int line, const char *funcname)
00509 {
00510    struct bucket_entry *p = internal_ao2_link(c, user_data, file, line, funcname);
00511 
00512    if (p) {
00513       __ao2_ref_debug(user_data, +1, tag, file, line, funcname);
00514       ao2_unlock(c);
00515    }
00516    return p;
00517 }
00518 
00519 void *__ao2_link(struct ao2_container *c, void *user_data)
00520 {
00521    struct bucket_entry *p = internal_ao2_link(c, user_data, __FILE__, __LINE__, __PRETTY_FUNCTION__);
00522 
00523    if (p) {
00524       __ao2_ref(user_data, +1);
00525       ao2_unlock(c);
00526    }
00527    return p;
00528 }
00529 
00530 /*!
00531  * \brief another convenience function is a callback that matches on address
00532  */
00533 int ao2_match_by_addr(void *user_data, void *arg, int flags)
00534 {
00535    return (user_data == arg) ? (CMP_MATCH | CMP_STOP) : 0;
00536 }
00537 
00538 /*
00539  * Unlink an object from the container
00540  * and destroy the associated * bucket_entry structure.
00541  */
00542 void *__ao2_unlink_debug(struct ao2_container *c, void *user_data, char *tag,
00543           char *file, int line, const char *funcname)
00544 {
00545    if (INTERNAL_OBJ(user_data) == NULL)   /* safety check on the argument */
00546       return NULL;
00547 
00548    __ao2_callback_debug(c, OBJ_UNLINK | OBJ_POINTER | OBJ_NODATA, ao2_match_by_addr, user_data, tag, file, line, funcname);
00549 
00550    return NULL;
00551 }
00552 
00553 void *__ao2_unlink(struct ao2_container *c, void *user_data)
00554 {
00555    if (INTERNAL_OBJ(user_data) == NULL)   /* safety check on the argument */
00556       return NULL;
00557 
00558    __ao2_callback(c, OBJ_UNLINK | OBJ_POINTER | OBJ_NODATA, ao2_match_by_addr, user_data);
00559 
00560    return NULL;
00561 }
00562 
00563 /*! 
00564  * \brief special callback that matches all 
00565  */ 
00566 static int cb_true(void *user_data, void *arg, int flags)
00567 {
00568    return CMP_MATCH;
00569 }
00570 
00571 /*!
00572  * \brief similar to cb_true, but is an ao2_callback_data_fn instead
00573  */
00574 static int cb_true_data(void *user_data, void *arg, void *data, int flags)
00575 {
00576    return CMP_MATCH;
00577 }
00578 
00579 /*!
00580  * Browse the container using different stategies accoding the flags.
00581  * \return Is a pointer to an object or to a list of object if OBJ_MULTIPLE is 
00582  * specified.
00583  * Luckily, for debug purposes, the added args (tag, file, line, funcname)
00584  * aren't an excessive load to the system, as the callback should not be
00585  * called as often as, say, the ao2_ref func is called.
00586  */
00587 static void *internal_ao2_callback(struct ao2_container *c,
00588                const enum search_flags flags, void *cb_fn, void *arg, void *data, enum ao2_callback_type type,
00589                char *tag, char *file, int line, const char *funcname)
00590 {
00591    int i, start, last;  /* search boundaries */
00592    void *ret = NULL;
00593    ao2_callback_fn *cb_default = NULL;
00594    ao2_callback_data_fn *cb_withdata = NULL;
00595    struct ao2_container *multi_container = NULL;
00596    struct ao2_iterator *multi_iterator = NULL;
00597 
00598    if (INTERNAL_OBJ(c) == NULL)  /* safety check on the argument */
00599       return NULL;
00600 
00601    /*
00602     * This logic is used so we can support OBJ_MULTIPLE with OBJ_NODATA
00603     * turned off.  This if statement checks for the special condition
00604     * where multiple items may need to be returned.
00605     */
00606    if ((flags & (OBJ_MULTIPLE | OBJ_NODATA)) == OBJ_MULTIPLE) {
00607       /* we need to return an ao2_iterator with the results,
00608        * as there could be more than one. the iterator will
00609        * hold the only reference to a container that has all the
00610        * matching objects linked into it, so when the iterator
00611        * is destroyed, the container will be automatically
00612        * destroyed as well.
00613        */
00614       if (!(multi_container = __ao2_container_alloc(1, NULL, NULL))) {
00615          return NULL;
00616       }
00617       if (!(multi_iterator = ast_calloc(1, sizeof(*multi_iterator)))) {
00618          ao2_ref(multi_container, -1);
00619          return NULL;
00620       }
00621    }
00622 
00623    /* override the match function if necessary */
00624    if (cb_fn == NULL) { /* if NULL, match everything */
00625       if (type == WITH_DATA) {
00626          cb_withdata = cb_true_data;
00627       } else {
00628          cb_default = cb_true;
00629       }
00630    } else {
00631       /* We do this here to avoid the per object casting penalty (even though
00632          that is probably optimized away anyway). */
00633       if (type == WITH_DATA) {
00634          cb_withdata = cb_fn;
00635       } else {
00636          cb_default = cb_fn;
00637       }
00638    }
00639 
00640    /*
00641     * XXX this can be optimized.
00642     * If we have a hash function and lookup by pointer,
00643     * run the hash function. Otherwise, scan the whole container
00644     * (this only for the time being. We need to optimize this.)
00645     */
00646    if ((flags & OBJ_POINTER)) /* we know hash can handle this case */
00647       start = i = c->hash_fn(arg, flags & OBJ_POINTER) % c->n_buckets;
00648    else        /* don't know, let's scan all buckets */
00649       start = i = -1;      /* XXX this must be fixed later. */
00650 
00651    /* determine the search boundaries: i..last-1 */
00652    if (i < 0) {
00653       start = i = 0;
00654       last = c->n_buckets;
00655    } else if ((flags & OBJ_CONTINUE)) {
00656       last = c->n_buckets;
00657    } else {
00658       last = i + 1;
00659    }
00660 
00661    ao2_lock(c);   /* avoid modifications to the content */
00662 
00663    for (; i < last ; i++) {
00664       /* scan the list with prev-cur pointers */
00665       struct bucket_entry *cur;
00666 
00667       AST_LIST_TRAVERSE_SAFE_BEGIN(&c->buckets[i], cur, entry) {
00668          int match = (CMP_MATCH | CMP_STOP);
00669 
00670          if (type == WITH_DATA) {
00671             match &= cb_withdata(EXTERNAL_OBJ(cur->astobj), arg, data, flags);
00672          } else {
00673             match &= cb_default(EXTERNAL_OBJ(cur->astobj), arg, flags);
00674          }
00675 
00676          /* we found the object, performing operations according flags */
00677          if (match == 0) { /* no match, no stop, continue */
00678             continue;
00679          } else if (match == CMP_STOP) {  /* no match but stop, we are done */
00680             i = last;
00681             break;
00682          }
00683 
00684          /* we have a match (CMP_MATCH) here */
00685          if (!(flags & OBJ_NODATA)) {  /* if must return the object, record the value */
00686             /* it is important to handle this case before the unlink */
00687             ret = EXTERNAL_OBJ(cur->astobj);
00688             if (!(flags & (OBJ_UNLINK | OBJ_MULTIPLE))) {
00689                if (tag)
00690                   __ao2_ref_debug(ret, 1, tag, file, line, funcname);
00691                else
00692                   __ao2_ref(ret, 1);
00693             }
00694          }
00695 
00696          /* If we are in OBJ_MULTIPLE mode and OBJ_NODATE is off, 
00697           * link the object into the container that will hold the results.
00698           */
00699          if (ret && (multi_container != NULL)) {
00700             if (tag) {
00701                __ao2_link_debug(multi_container, ret, tag, file, line, funcname);
00702             } else {
00703                __ao2_link(multi_container, ret);
00704             }
00705             ret = NULL;
00706          }
00707 
00708          if (flags & OBJ_UNLINK) {  /* must unlink */
00709             /* we are going to modify the container, so update version */
00710             ast_atomic_fetchadd_int(&c->version, 1);
00711             AST_LIST_REMOVE_CURRENT(entry);
00712             /* update number of elements */
00713             ast_atomic_fetchadd_int(&c->elements, -1);
00714 
00715             /* - When unlinking and not returning the result, (OBJ_NODATA), the ref from the container
00716              * must be decremented.
00717              * - When unlinking with OBJ_MULTIPLE the ref from the original container
00718              * must be decremented regardless if OBJ_NODATA is used. This is because the result is
00719              * returned in a new container that already holds its own ref for the object. If the ref
00720              * from the original container is not accounted for here a memory leak occurs. */
00721             if (flags & (OBJ_NODATA | OBJ_MULTIPLE)) {
00722                if (tag)
00723                   __ao2_ref_debug(EXTERNAL_OBJ(cur->astobj), -1, tag, file, line, funcname);
00724                else
00725                   __ao2_ref(EXTERNAL_OBJ(cur->astobj), -1);
00726             }
00727             ast_free(cur); /* free the link record */
00728          }
00729 
00730          if ((match & CMP_STOP) || !(flags & OBJ_MULTIPLE)) {
00731             /* We found our only (or last) match, so force an exit from
00732                the outside loop. */
00733             i = last;
00734             break;
00735          }
00736       }
00737       AST_LIST_TRAVERSE_SAFE_END;
00738 
00739       if (ret) {
00740          break;
00741       }
00742 
00743       if (i == c->n_buckets - 1 && (flags & OBJ_POINTER) && (flags & OBJ_CONTINUE)) {
00744          /* Move to the beginning to ensure we check every bucket */
00745          i = -1;
00746          last = start;
00747       }
00748    }
00749    ao2_unlock(c);
00750 
00751    /* if multi_container was created, we are returning multiple objects */
00752    if (multi_container != NULL) {
00753       *multi_iterator = ao2_iterator_init(multi_container,
00754                       AO2_ITERATOR_DONTLOCK | AO2_ITERATOR_UNLINK | AO2_ITERATOR_MALLOCD);
00755       ao2_ref(multi_container, -1);
00756       return multi_iterator;
00757    } else {
00758       return ret;
00759    }
00760 }
00761 
00762 void *__ao2_callback_debug(struct ao2_container *c,
00763             const enum search_flags flags,
00764             ao2_callback_fn *cb_fn, void *arg,
00765             char *tag, char *file, int line, const char *funcname)
00766 {
00767    return internal_ao2_callback(c,flags, cb_fn, arg, NULL, DEFAULT, tag, file, line, funcname);
00768 }
00769 
00770 void *__ao2_callback(struct ao2_container *c, const enum search_flags flags,
00771            ao2_callback_fn *cb_fn, void *arg)
00772 {
00773    return internal_ao2_callback(c,flags, cb_fn, arg, NULL, DEFAULT, NULL, NULL, 0, NULL);
00774 }
00775 
00776 void *__ao2_callback_data_debug(struct ao2_container *c,
00777             const enum search_flags flags,
00778             ao2_callback_data_fn *cb_fn, void *arg, void *data,
00779             char *tag, char *file, int line, const char *funcname)
00780 {
00781    return internal_ao2_callback(c, flags, cb_fn, arg, data, WITH_DATA, tag, file, line, funcname);
00782 }
00783 
00784 void *__ao2_callback_data(struct ao2_container *c, const enum search_flags flags,
00785            ao2_callback_data_fn *cb_fn, void *arg, void *data)
00786 {
00787    return internal_ao2_callback(c, flags, cb_fn, arg, data, WITH_DATA, NULL, NULL, 0, NULL);
00788 }
00789 
00790 /*!
00791  * the find function just invokes the default callback with some reasonable flags.
00792  */
00793 void *__ao2_find_debug(struct ao2_container *c, void *arg, enum search_flags flags, char *tag, char *file, int line, const char *funcname)
00794 {
00795    return __ao2_callback_debug(c, flags, c->cmp_fn, arg, tag, file, line, funcname);
00796 }
00797 
00798 void *__ao2_find(struct ao2_container *c, void *arg, enum search_flags flags)
00799 {
00800    return __ao2_callback(c, flags, c->cmp_fn, arg);
00801 }
00802 
00803 /*!
00804  * initialize an iterator so we start from the first object
00805  */
00806 struct ao2_iterator ao2_iterator_init(struct ao2_container *c, int flags)
00807 {
00808    struct ao2_iterator a = {
00809       .c = c,
00810       .flags = flags
00811    };
00812 
00813    ao2_ref(c, +1);
00814    
00815    return a;
00816 }
00817 
00818 /*!
00819  * destroy an iterator
00820  */
00821 void ao2_iterator_destroy(struct ao2_iterator *i)
00822 {
00823    ao2_ref(i->c, -1);
00824    if (i->flags & AO2_ITERATOR_MALLOCD) {
00825       ast_free(i);
00826    } else {
00827       i->c = NULL;
00828    }
00829 }
00830 
00831 /*
00832  * move to the next element in the container.
00833  */
00834 static void *internal_ao2_iterator_next(struct ao2_iterator *a, struct bucket_entry **q)
00835 {
00836    int lim;
00837    struct bucket_entry *p = NULL;
00838    void *ret = NULL;
00839 
00840    *q = NULL;
00841    
00842    if (INTERNAL_OBJ(a->c) == NULL)
00843       return NULL;
00844 
00845    if (!(a->flags & AO2_ITERATOR_DONTLOCK))
00846       ao2_lock(a->c);
00847 
00848    /* optimization. If the container is unchanged and
00849     * we have a pointer, try follow it
00850     */
00851    if (a->c->version == a->c_version && (p = a->obj)) {
00852       if ((p = AST_LIST_NEXT(p, entry)))
00853          goto found;
00854       /* nope, start from the next bucket */
00855       a->bucket++;
00856       a->version = 0;
00857       a->obj = NULL;
00858    }
00859 
00860    lim = a->c->n_buckets;
00861 
00862    /* Browse the buckets array, moving to the next
00863     * buckets if we don't find the entry in the current one.
00864     * Stop when we find an element with version number greater
00865     * than the current one (we reset the version to 0 when we
00866     * switch buckets).
00867     */
00868    for (; a->bucket < lim; a->bucket++, a->version = 0) {
00869       /* scan the current bucket */
00870       AST_LIST_TRAVERSE(&a->c->buckets[a->bucket], p, entry) {
00871          if (p->version > a->version)
00872             goto found;
00873       }
00874    }
00875 
00876 found:
00877    if (p) {
00878       ret = EXTERNAL_OBJ(p->astobj);
00879       if (a->flags & AO2_ITERATOR_UNLINK) {
00880          /* we are going to modify the container, so update version */
00881          ast_atomic_fetchadd_int(&a->c->version, 1);
00882          AST_LIST_REMOVE(&a->c->buckets[a->bucket], p, entry);
00883          /* update number of elements */
00884          ast_atomic_fetchadd_int(&a->c->elements, -1);
00885          a->version = 0;
00886          a->obj = NULL;
00887          a->c_version = a->c->version;
00888          ast_free(p);
00889       } else {
00890          a->version = p->version;
00891          a->obj = p;
00892          a->c_version = a->c->version;
00893          /* inc refcount of returned object */
00894          *q = p;
00895       }
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_entry *p;
00904    void *ret = NULL;
00905 
00906    ret = internal_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_entry *p = NULL;
00922    void *ret = NULL;
00923 
00924    ret = internal_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_entry *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_entry *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    struct ast_cli_args *a = (struct ast_cli_args *) arg;
00996    char *s = (char *)obj;
00997 
00998    ast_cli(a->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, "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, "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 }

Generated on Sat Mar 10 01:54:04 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7