Wed Oct 14 15:01:56 2009

Asterisk developer's documentation


linkedlists.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2006, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  * Kevin P. Fleming <kpfleming@digium.com>
00008  *
00009  * See http://www.asterisk.org for more information about
00010  * the Asterisk project. Please do not directly contact
00011  * any of the maintainers of this project for assistance;
00012  * the project provides a web site, mailing lists and IRC
00013  * channels for your use.
00014  *
00015  * This program is free software, distributed under the terms of
00016  * the GNU General Public License Version 2. See the LICENSE file
00017  * at the top of the source tree.
00018  */
00019 
00020 #ifndef ASTERISK_LINKEDLISTS_H
00021 #define ASTERISK_LINKEDLISTS_H
00022 
00023 #include "asterisk/lock.h"
00024 
00025 /*!
00026   \file linkedlists.h
00027   \brief A set of macros to manage forward-linked lists.
00028 */
00029 
00030 /*!
00031   \brief Locks a list.
00032   \param head This is a pointer to the list head structure
00033 
00034   This macro attempts to place an exclusive lock in the
00035   list head structure pointed to by head.
00036   Returns 0 on success, non-zero on failure
00037 */
00038 #define AST_LIST_LOCK(head)                  \
00039    ast_mutex_lock(&(head)->lock) 
00040 
00041 /*!
00042   \brief Write locks a list.
00043   \param head This is a pointer to the list head structure
00044 
00045   This macro attempts to place an exclusive write lock in the
00046   list head structure pointed to by head.
00047   Returns 0 on success, non-zero on failure
00048 */
00049 #define AST_RWLIST_WRLOCK(head)                                         \
00050         ast_rwlock_wrlock(&(head)->lock)
00051 
00052 /*!
00053   \brief Read locks a list.
00054   \param head This is a pointer to the list head structure
00055 
00056   This macro attempts to place a read lock in the
00057   list head structure pointed to by head.
00058   Returns 0 on success, non-zero on failure
00059 */
00060 #define AST_RWLIST_RDLOCK(head)                                         \
00061         ast_rwlock_rdlock(&(head)->lock)
00062    
00063 /*!
00064   \brief Locks a list, without blocking if the list is locked.
00065   \param head This is a pointer to the list head structure
00066 
00067   This macro attempts to place an exclusive lock in the
00068   list head structure pointed to by head.
00069   Returns 0 on success, non-zero on failure
00070 */
00071 #define AST_LIST_TRYLOCK(head)                  \
00072    ast_mutex_trylock(&(head)->lock) 
00073 
00074 /*!
00075   \brief Write locks a list, without blocking if the list is locked.
00076   \param head This is a pointer to the list head structure
00077 
00078   This macro attempts to place an exclusive write lock in the
00079   list head structure pointed to by head.
00080   Returns 0 on success, non-zero on failure
00081 */
00082 #define AST_RWLIST_TRYWRLOCK(head)                                      \
00083         ast_rwlock_trywrlock(&(head)->lock)
00084 
00085 /*!
00086   \brief Read locks a list, without blocking if the list is locked.
00087   \param head This is a pointer to the list head structure
00088 
00089   This macro attempts to place a read lock in the
00090   list head structure pointed to by head.
00091   Returns 0 on success, non-zero on failure
00092 */
00093 #define AST_RWLIST_TRYRDLOCK(head)                                      \
00094         ast_rwlock_tryrdlock(&(head)->lock)
00095    
00096 /*!
00097   \brief Attempts to unlock a list.
00098   \param head This is a pointer to the list head structure
00099 
00100   This macro attempts to remove an exclusive lock from the
00101   list head structure pointed to by head. If the list
00102   was not locked by this thread, this macro has no effect.
00103 */
00104 #define AST_LIST_UNLOCK(head)                   \
00105    ast_mutex_unlock(&(head)->lock)
00106 
00107 /*!
00108   \brief Attempts to unlock a read/write based list.
00109   \param head This is a pointer to the list head structure
00110 
00111   This macro attempts to remove a read or write lock from the
00112   list head structure pointed to by head. If the list
00113   was not locked by this thread, this macro has no effect.
00114 */
00115 #define AST_RWLIST_UNLOCK(head)                                         \
00116         ast_rwlock_unlock(&(head)->lock)
00117 
00118 /*!
00119   \brief Defines a structure to be used to hold a list of specified type.
00120   \param name This will be the name of the defined structure.
00121   \param type This is the type of each list entry.
00122 
00123   This macro creates a structure definition that can be used
00124   to hold a list of the entries of type \a type. It does not actually
00125   declare (allocate) a structure; to do that, either follow this
00126   macro with the desired name of the instance you wish to declare,
00127   or use the specified \a name to declare instances elsewhere.
00128 
00129   Example usage:
00130   \code
00131   static AST_LIST_HEAD(entry_list, entry) entries;
00132   \endcode
00133 
00134   This would define \c struct \c entry_list, and declare an instance of it named
00135   \a entries, all intended to hold a list of type \c struct \c entry.
00136 */
00137 #define AST_LIST_HEAD(name, type)               \
00138 struct name {                       \
00139    struct type *first;                 \
00140    struct type *last;                  \
00141    ast_mutex_t lock;                \
00142 }
00143 
00144 /*!
00145   \brief Defines a structure to be used to hold a read/write list of specified type.
00146   \param name This will be the name of the defined structure.
00147   \param type This is the type of each list entry.
00148 
00149   This macro creates a structure definition that can be used
00150   to hold a list of the entries of type \a type. It does not actually
00151   declare (allocate) a structure; to do that, either follow this
00152   macro with the desired name of the instance you wish to declare,
00153   or use the specified \a name to declare instances elsewhere.
00154 
00155   Example usage:
00156   \code
00157   static AST_RWLIST_HEAD(entry_list, entry) entries;
00158   \endcode
00159 
00160   This would define \c struct \c entry_list, and declare an instance of it named
00161   \a entries, all intended to hold a list of type \c struct \c entry.
00162 */
00163 #define AST_RWLIST_HEAD(name, type)                                     \
00164 struct name {                                                           \
00165         struct type *first;                                             \
00166         struct type *last;                                              \
00167         ast_rwlock_t lock;                                              \
00168 }
00169 
00170 /*!
00171   \brief Defines a structure to be used to hold a list of specified type (with no lock).
00172   \param name This will be the name of the defined structure.
00173   \param type This is the type of each list entry.
00174 
00175   This macro creates a structure definition that can be used
00176   to hold a list of the entries of type \a type. It does not actually
00177   declare (allocate) a structure; to do that, either follow this
00178   macro with the desired name of the instance you wish to declare,
00179   or use the specified \a name to declare instances elsewhere.
00180 
00181   Example usage:
00182   \code
00183   static AST_LIST_HEAD_NOLOCK(entry_list, entry) entries;
00184   \endcode
00185 
00186   This would define \c struct \c entry_list, and declare an instance of it named
00187   \a entries, all intended to hold a list of type \c struct \c entry.
00188 */
00189 #define AST_LIST_HEAD_NOLOCK(name, type)           \
00190 struct name {                       \
00191    struct type *first;                 \
00192    struct type *last;                  \
00193 }
00194 
00195 /*!
00196   \brief Defines initial values for a declaration of AST_LIST_HEAD
00197 */
00198 #define AST_LIST_HEAD_INIT_VALUE {     \
00199    .first = NULL,             \
00200    .last = NULL,              \
00201    .lock = AST_MUTEX_INIT_VALUE,       \
00202    }
00203 
00204 /*!
00205   \brief Defines initial values for a declaration of AST_RWLIST_HEAD
00206 */
00207 #define AST_RWLIST_HEAD_INIT_VALUE      {               \
00208         .first = NULL,                                  \
00209         .last = NULL,                                   \
00210         .lock = AST_RWLOCK_INIT_VALUE,                  \
00211         }
00212 
00213 /*!
00214   \brief Defines initial values for a declaration of AST_LIST_HEAD_NOLOCK
00215 */
00216 #define AST_LIST_HEAD_NOLOCK_INIT_VALUE   {  \
00217    .first = NULL,             \
00218    .last = NULL,              \
00219    }
00220 
00221 /*!
00222   \brief Defines a structure to be used to hold a list of specified type, statically initialized.
00223   \param name This will be the name of the defined structure.
00224   \param type This is the type of each list entry.
00225 
00226   This macro creates a structure definition that can be used
00227   to hold a list of the entries of type \a type, and allocates an instance
00228   of it, initialized to be empty.
00229 
00230   Example usage:
00231   \code
00232   static AST_LIST_HEAD_STATIC(entry_list, entry);
00233   \endcode
00234 
00235   This would define \c struct \c entry_list, intended to hold a list of
00236   type \c struct \c entry.
00237 */
00238 #if defined(AST_MUTEX_INIT_W_CONSTRUCTORS)
00239 #define AST_LIST_HEAD_STATIC(name, type)           \
00240 struct name {                       \
00241    struct type *first;                 \
00242    struct type *last;                  \
00243    ast_mutex_t lock;                \
00244 } name;                          \
00245 static void  __attribute__((constructor)) init_##name(void)    \
00246 {                          \
00247         AST_LIST_HEAD_INIT(&name);              \
00248 }                          \
00249 static void  __attribute__((destructor)) fini_##name(void)     \
00250 {                          \
00251         AST_LIST_HEAD_DESTROY(&name);              \
00252 }                          \
00253 struct __dummy_##name
00254 #else
00255 #define AST_LIST_HEAD_STATIC(name, type)           \
00256 struct name {                       \
00257    struct type *first;                 \
00258    struct type *last;                  \
00259    ast_mutex_t lock;                \
00260 } name = AST_LIST_HEAD_INIT_VALUE
00261 #endif
00262 
00263 /*!
00264   \brief Defines a structure to be used to hold a read/write list of specified type, statically initialized.
00265   \param name This will be the name of the defined structure.
00266   \param type This is the type of each list entry.
00267 
00268   This macro creates a structure definition that can be used
00269   to hold a list of the entries of type \a type, and allocates an instance
00270   of it, initialized to be empty.
00271 
00272   Example usage:
00273   \code
00274   static AST_RWLIST_HEAD_STATIC(entry_list, entry);
00275   \endcode
00276 
00277   This would define \c struct \c entry_list, intended to hold a list of
00278   type \c struct \c entry.
00279 */
00280 #ifndef HAVE_PTHREAD_RWLOCK_INITIALIZER
00281 #define AST_RWLIST_HEAD_STATIC(name, type)                              \
00282 struct name {                                                           \
00283         struct type *first;                                             \
00284         struct type *last;                                              \
00285         ast_rwlock_t lock;                                              \
00286 } name;                                                                 \
00287 static void  __attribute__((constructor)) init_##name(void)            \
00288 {                                                                       \
00289         AST_RWLIST_HEAD_INIT(&name);                                    \
00290 }                                                                       \
00291 static void  __attribute__((destructor)) fini_##name(void)             \
00292 {                                                                       \
00293         AST_RWLIST_HEAD_DESTROY(&name);                                 \
00294 }                                                                       \
00295 struct __dummy_##name
00296 #else
00297 #define AST_RWLIST_HEAD_STATIC(name, type)                              \
00298 struct name {                                                           \
00299         struct type *first;                                             \
00300         struct type *last;                                              \
00301         ast_rwlock_t lock;                                              \
00302 } name = AST_RWLIST_HEAD_INIT_VALUE
00303 #endif
00304 
00305 /*!
00306   \brief Defines a structure to be used to hold a list of specified type, statically initialized.
00307 
00308   This is the same as AST_LIST_HEAD_STATIC, except without the lock included.
00309 */
00310 #define AST_LIST_HEAD_NOLOCK_STATIC(name, type)          \
00311 struct name {                       \
00312    struct type *first;                 \
00313    struct type *last;                  \
00314 } name = AST_LIST_HEAD_NOLOCK_INIT_VALUE
00315 
00316 /*!
00317   \brief Initializes a list head structure with a specified first entry.
00318   \param head This is a pointer to the list head structure
00319   \param entry pointer to the list entry that will become the head of the list
00320 
00321   This macro initializes a list head structure by setting the head
00322   entry to the supplied value and recreating the embedded lock.
00323 */
00324 #define AST_LIST_HEAD_SET(head, entry) do {           \
00325    (head)->first = (entry);               \
00326    (head)->last = (entry);                \
00327    ast_mutex_init(&(head)->lock);               \
00328 } while (0)
00329 
00330 /*!
00331   \brief Initializes an rwlist head structure with a specified first entry.
00332   \param head This is a pointer to the list head structure
00333   \param entry pointer to the list entry that will become the head of the list
00334 
00335   This macro initializes a list head structure by setting the head
00336   entry to the supplied value and recreating the embedded lock.
00337 */
00338 #define AST_RWLIST_HEAD_SET(head, entry) do {                           \
00339         (head)->first = (entry);                                        \
00340         (head)->last = (entry);                                         \
00341         ast_rwlock_init(&(head)->lock);                                 \
00342 } while (0)
00343 
00344 /*!
00345   \brief Initializes a list head structure with a specified first entry.
00346   \param head This is a pointer to the list head structure
00347   \param entry pointer to the list entry that will become the head of the list
00348 
00349   This macro initializes a list head structure by setting the head
00350   entry to the supplied value.
00351 */
00352 #define AST_LIST_HEAD_SET_NOLOCK(head, entry) do {       \
00353    (head)->first = (entry);               \
00354    (head)->last = (entry);                \
00355 } while (0)
00356 
00357 /*!
00358   \brief Declare a forward link structure inside a list entry.
00359   \param type This is the type of each list entry.
00360 
00361   This macro declares a structure to be used to link list entries together.
00362   It must be used inside the definition of the structure named in
00363   \a type, as follows:
00364 
00365   \code
00366   struct list_entry {
00367    ...
00368    AST_LIST_ENTRY(list_entry) list;
00369   }
00370   \endcode
00371 
00372   The field name \a list here is arbitrary, and can be anything you wish.
00373 */
00374 #define AST_LIST_ENTRY(type)                 \
00375 struct {                      \
00376    struct type *next;                  \
00377 }
00378 
00379 #define AST_RWLIST_ENTRY AST_LIST_ENTRY
00380  
00381 /*!
00382   \brief Returns the first entry contained in a list.
00383   \param head This is a pointer to the list head structure
00384  */
00385 #define  AST_LIST_FIRST(head) ((head)->first)
00386 
00387 #define AST_RWLIST_FIRST AST_LIST_FIRST
00388 
00389 /*!
00390   \brief Returns the last entry contained in a list.
00391   \param head This is a pointer to the list head structure
00392  */
00393 #define  AST_LIST_LAST(head)  ((head)->last)
00394 
00395 #define AST_RWLIST_LAST AST_LIST_LAST
00396 
00397 /*!
00398   \brief Returns the next entry in the list after the given entry.
00399   \param elm This is a pointer to the current entry.
00400   \param field This is the name of the field (declared using AST_LIST_ENTRY())
00401   used to link entries of this list together.
00402 */
00403 #define AST_LIST_NEXT(elm, field)   ((elm)->field.next)
00404 
00405 #define AST_RWLIST_NEXT AST_LIST_NEXT
00406 
00407 /*!
00408   \brief Checks whether the specified list contains any entries.
00409   \param head This is a pointer to the list head structure
00410 
00411   Returns non-zero if the list has entries, zero if not.
00412  */
00413 #define  AST_LIST_EMPTY(head) (AST_LIST_FIRST(head) == NULL)
00414 
00415 #define AST_RWLIST_EMPTY AST_LIST_EMPTY
00416 
00417 /*!
00418   \brief Loops over (traverses) the entries in a list.
00419   \param head This is a pointer to the list head structure
00420   \param var This is the name of the variable that will hold a pointer to the
00421   current list entry on each iteration. It must be declared before calling
00422   this macro.
00423   \param field This is the name of the field (declared using AST_LIST_ENTRY())
00424   used to link entries of this list together.
00425 
00426   This macro is use to loop over (traverse) the entries in a list. It uses a
00427   \a for loop, and supplies the enclosed code with a pointer to each list
00428   entry as it loops. It is typically used as follows:
00429   \code
00430   static AST_LIST_HEAD(entry_list, list_entry) entries;
00431   ...
00432   struct list_entry {
00433    ...
00434    AST_LIST_ENTRY(list_entry) list;
00435   }
00436   ...
00437   struct list_entry *current;
00438   ...
00439   AST_LIST_TRAVERSE(&entries, current, list) {
00440      (do something with current here)
00441   }
00442   \endcode
00443   \warning If you modify the forward-link pointer contained in the \a current entry while
00444   inside the loop, the behavior will be unpredictable. At a minimum, the following
00445   macros will modify the forward-link pointer, and should not be used inside
00446   AST_LIST_TRAVERSE() against the entry pointed to by the \a current pointer without
00447   careful consideration of their consequences:
00448   \li AST_LIST_NEXT() (when used as an lvalue)
00449   \li AST_LIST_INSERT_AFTER()
00450   \li AST_LIST_INSERT_HEAD()
00451   \li AST_LIST_INSERT_TAIL()
00452 */
00453 #define AST_LIST_TRAVERSE(head,var,field)             \
00454    for((var) = (head)->first; (var); (var) = (var)->field.next)
00455 
00456 #define AST_RWLIST_TRAVERSE AST_LIST_TRAVERSE
00457 
00458 /*!
00459   \brief Loops safely over (traverses) the entries in a list.
00460   \param head This is a pointer to the list head structure
00461   \param var This is the name of the variable that will hold a pointer to the
00462   current list entry on each iteration. It must be declared before calling
00463   this macro.
00464   \param field This is the name of the field (declared using AST_LIST_ENTRY())
00465   used to link entries of this list together.
00466 
00467   This macro is used to safely loop over (traverse) the entries in a list. It
00468   uses a \a for loop, and supplies the enclosed code with a pointer to each list
00469   entry as it loops. It is typically used as follows:
00470 
00471   \code
00472   static AST_LIST_HEAD(entry_list, list_entry) entries;
00473   ...
00474   struct list_entry {
00475    ...
00476    AST_LIST_ENTRY(list_entry) list;
00477   }
00478   ...
00479   struct list_entry *current;
00480   ...
00481   AST_LIST_TRAVERSE_SAFE_BEGIN(&entries, current, list) {
00482      (do something with current here)
00483   }
00484   AST_LIST_TRAVERSE_SAFE_END;
00485   \endcode
00486 
00487   It differs from AST_LIST_TRAVERSE() in that the code inside the loop can modify
00488   (or even free, after calling AST_LIST_REMOVE_CURRENT()) the entry pointed to by
00489   the \a current pointer without affecting the loop traversal.
00490 */
00491 #define AST_LIST_TRAVERSE_SAFE_BEGIN(head, var, field) {          \
00492    typeof((head)->first) __list_next;                 \
00493    typeof((head)->first) __list_prev = NULL;             \
00494    typeof((head)->first) __new_prev = NULL;              \
00495    for ((var) = (head)->first, __new_prev = (var),             \
00496          __list_next = (var) ? (var)->field.next : NULL;          \
00497         (var);                         \
00498         __list_prev = __new_prev, (var) = __list_next,            \
00499         __new_prev = (var),                     \
00500         __list_next = (var) ? (var)->field.next : NULL            \
00501        )
00502 
00503 #define AST_RWLIST_TRAVERSE_SAFE_BEGIN AST_LIST_TRAVERSE_SAFE_BEGIN
00504 
00505 /*!
00506   \brief Removes the \a current entry from a list during a traversal.
00507   \param head This is a pointer to the list head structure
00508   \param field This is the name of the field (declared using AST_LIST_ENTRY())
00509   used to link entries of this list together.
00510 
00511   \note This macro can \b only be used inside an AST_LIST_TRAVERSE_SAFE_BEGIN()
00512   block; it is used to unlink the current entry from the list without affecting
00513   the list traversal (and without having to re-traverse the list to modify the
00514   previous entry, if any).
00515  */
00516 #define AST_LIST_REMOVE_CURRENT(head, field) do { \
00517    __new_prev->field.next = NULL;                     \
00518    __new_prev = __list_prev;                    \
00519    if (__list_prev)                       \
00520       __list_prev->field.next = __list_next;             \
00521    else                             \
00522       (head)->first = __list_next;                 \
00523    if (!__list_next)                      \
00524       (head)->last = __list_prev; \
00525    } while (0)
00526 
00527 #define AST_RWLIST_REMOVE_CURRENT AST_LIST_REMOVE_CURRENT
00528 
00529 /*!
00530   \brief Inserts a list entry before the current entry during a traversal.
00531   \param head This is a pointer to the list head structure
00532   \param elm This is a pointer to the entry to be inserted.
00533   \param field This is the name of the field (declared using AST_LIST_ENTRY())
00534   used to link entries of this list together.
00535 
00536   \note This macro can \b only be used inside an AST_LIST_TRAVERSE_SAFE_BEGIN()
00537   block.
00538  */
00539 #define AST_LIST_INSERT_BEFORE_CURRENT(head, elm, field) do {     \
00540    if (__list_prev) {                  \
00541       (elm)->field.next = __list_prev->field.next;    \
00542       __list_prev->field.next = elm;            \
00543    } else {                   \
00544       (elm)->field.next = (head)->first;        \
00545       (head)->first = (elm);              \
00546    }                       \
00547    __new_prev = (elm);                 \
00548 } while (0)
00549 
00550 #define AST_RWLIST_INSERT_BEFORE_CURRENT AST_LIST_INSERT_BEFORE_CURRENT
00551 
00552 /*!
00553   \brief Closes a safe loop traversal block.
00554  */
00555 #define AST_LIST_TRAVERSE_SAFE_END  }
00556 
00557 #define AST_RWLIST_TRAVERSE_SAFE_END AST_LIST_TRAVERSE_SAFE_END
00558 
00559 /*!
00560   \brief Initializes a list head structure.
00561   \param head This is a pointer to the list head structure
00562 
00563   This macro initializes a list head structure by setting the head
00564   entry to \a NULL (empty list) and recreating the embedded lock.
00565 */
00566 #define AST_LIST_HEAD_INIT(head) {              \
00567    (head)->first = NULL;                  \
00568    (head)->last = NULL;                \
00569    ast_mutex_init(&(head)->lock);               \
00570 }
00571 
00572 /*!
00573   \brief Initializes an rwlist head structure.
00574   \param head This is a pointer to the list head structure
00575 
00576   This macro initializes a list head structure by setting the head
00577   entry to \a NULL (empty list) and recreating the embedded lock.
00578 */
00579 #define AST_RWLIST_HEAD_INIT(head) {                                    \
00580         (head)->first = NULL;                                           \
00581         (head)->last = NULL;                                            \
00582         ast_rwlock_init(&(head)->lock);                                 \
00583 }
00584 
00585 /*!
00586   \brief Destroys a list head structure.
00587   \param head This is a pointer to the list head structure
00588 
00589   This macro destroys a list head structure by setting the head
00590   entry to \a NULL (empty list) and destroying the embedded lock.
00591   It does not free the structure from memory.
00592 */
00593 #define AST_LIST_HEAD_DESTROY(head) {              \
00594    (head)->first = NULL;                  \
00595    (head)->last = NULL;                \
00596    ast_mutex_destroy(&(head)->lock);            \
00597 }
00598 
00599 /*!
00600   \brief Destroys an rwlist head structure.
00601   \param head This is a pointer to the list head structure
00602 
00603   This macro destroys a list head structure by setting the head
00604   entry to \a NULL (empty list) and destroying the embedded lock.
00605   It does not free the structure from memory.
00606 */
00607 #define AST_RWLIST_HEAD_DESTROY(head) {                                 \
00608         (head)->first = NULL;                                           \
00609         (head)->last = NULL;                                            \
00610         ast_rwlock_destroy(&(head)->lock);                              \
00611 }
00612 
00613 /*!
00614   \brief Initializes a list head structure.
00615   \param head This is a pointer to the list head structure
00616 
00617   This macro initializes a list head structure by setting the head
00618   entry to \a NULL (empty list). There is no embedded lock handling
00619   with this macro.
00620 */
00621 #define AST_LIST_HEAD_INIT_NOLOCK(head) {          \
00622    (head)->first = NULL;                  \
00623    (head)->last = NULL;                \
00624 }
00625 
00626 /*!
00627   \brief Inserts a list entry after a given entry.
00628   \param head This is a pointer to the list head structure
00629   \param listelm This is a pointer to the entry after which the new entry should
00630   be inserted.
00631   \param elm This is a pointer to the entry to be inserted.
00632   \param field This is the name of the field (declared using AST_LIST_ENTRY())
00633   used to link entries of this list together.
00634  */
00635 #define AST_LIST_INSERT_AFTER(head, listelm, elm, field) do {     \
00636    (elm)->field.next = (listelm)->field.next;         \
00637    (listelm)->field.next = (elm);               \
00638    if ((head)->last == (listelm))               \
00639       (head)->last = (elm);               \
00640 } while (0)
00641 
00642 #define AST_RWLIST_INSERT_AFTER AST_LIST_INSERT_AFTER
00643 
00644 /*!
00645   \brief Inserts a list entry at the head of a list.
00646   \param head This is a pointer to the list head structure
00647   \param elm This is a pointer to the entry to be inserted.
00648   \param field This is the name of the field (declared using AST_LIST_ENTRY())
00649   used to link entries of this list together.
00650  */
00651 #define AST_LIST_INSERT_HEAD(head, elm, field) do {         \
00652       (elm)->field.next = (head)->first;        \
00653       (head)->first = (elm);              \
00654       if (!(head)->last)               \
00655          (head)->last = (elm);            \
00656 } while (0)
00657 
00658 #define AST_RWLIST_INSERT_HEAD AST_LIST_INSERT_HEAD
00659 
00660 /*!
00661   \brief Appends a list entry to the tail of a list.
00662   \param head This is a pointer to the list head structure
00663   \param elm This is a pointer to the entry to be appended.
00664   \param field This is the name of the field (declared using AST_LIST_ENTRY())
00665   used to link entries of this list together.
00666 
00667   Note: The link field in the appended entry is \b not modified, so if it is
00668   actually the head of a list itself, the entire list will be appended
00669   temporarily (until the next AST_LIST_INSERT_TAIL is performed).
00670  */
00671 #define AST_LIST_INSERT_TAIL(head, elm, field) do {         \
00672       if (!(head)->first) {                  \
00673       (head)->first = (elm);              \
00674       (head)->last = (elm);               \
00675       } else {                      \
00676       (head)->last->field.next = (elm);         \
00677       (head)->last = (elm);               \
00678       }                          \
00679 } while (0)
00680 
00681 #define AST_RWLIST_INSERT_TAIL AST_LIST_INSERT_TAIL
00682 
00683 /*!
00684   \brief Appends a whole list to the tail of a list.
00685   \param head This is a pointer to the list head structure
00686   \param list This is a pointer to the list to be appended.
00687   \param field This is the name of the field (declared using AST_LIST_ENTRY())
00688   used to link entries of the list together.
00689 
00690   Note: The source list (the \a list parameter) will be empty after
00691   calling this macro (the list entries are \b moved to the target list).
00692  */
00693 #define AST_LIST_APPEND_LIST(head, list, field) do {        \
00694    if (!(list)->first) {                  \
00695       break;                     \
00696    }                       \
00697    if (!(head)->first) {                  \
00698       (head)->first = (list)->first;            \
00699       (head)->last = (list)->last;           \
00700    } else {                   \
00701       (head)->last->field.next = (list)->first;    \
00702       (head)->last = (list)->last;           \
00703    }                       \
00704    (list)->first = NULL;                  \
00705    (list)->last = NULL;                \
00706 } while (0)
00707 
00708 #define AST_RWLIST_APPEND_LIST AST_LIST_APPEND_LIST
00709 
00710 /*!
00711   \brief Inserts a whole list after a specific entry in a list
00712   \param head This is a pointer to the list head structure
00713   \param list This is a pointer to the list to be inserted.
00714   \param elm This is a pointer to the entry after which the new list should
00715   be inserted.
00716   \param field This is the name of the field (declared using AST_LIST_ENTRY())
00717   used to link entries of the lists together.
00718 
00719   Note: The source list (the \a list parameter) will be empty after
00720   calling this macro (the list entries are \b moved to the target list).
00721  */
00722 #define AST_LIST_INSERT_LIST_AFTER(head, list, elm, field) do {      \
00723    (list)->last->field.next = (elm)->field.next;         \
00724    (elm)->field.next = (list)->first;           \
00725    if ((head)->last == elm) {             \
00726       (head)->last = (list)->last;           \
00727    }                       \
00728    (list)->first = NULL;                  \
00729    (list)->last = NULL;                \
00730 } while(0)
00731 
00732 #define AST_RWLIST_INSERT_LIST_AFTER AST_LIST_INSERT_LIST_AFTER
00733 
00734 /*!
00735   \brief Removes and returns the head entry from a list.
00736   \param head This is a pointer to the list head structure
00737   \param field This is the name of the field (declared using AST_LIST_ENTRY())
00738   used to link entries of this list together.
00739 
00740   Removes the head entry from the list, and returns a pointer to it.
00741   This macro is safe to call on an empty list.
00742  */
00743 #define AST_LIST_REMOVE_HEAD(head, field) ({          \
00744       typeof((head)->first) cur = (head)->first;      \
00745       if (cur) {                 \
00746          (head)->first = cur->field.next;    \
00747          cur->field.next = NULL;          \
00748          if ((head)->last == cur)         \
00749             (head)->last = NULL;       \
00750       }                    \
00751       cur;                    \
00752    })
00753 
00754 #define AST_RWLIST_REMOVE_HEAD AST_LIST_REMOVE_HEAD
00755 
00756 /*!
00757   \brief Removes a specific entry from a list.
00758   \param head This is a pointer to the list head structure
00759   \param elm This is a pointer to the entry to be removed.
00760   \param field This is the name of the field (declared using AST_LIST_ENTRY())
00761   used to link entries of this list together.
00762   \warning The removed entry is \b not freed nor modified in any way.
00763  */
00764 #define AST_LIST_REMOVE(head, elm, field) ({               \
00765    __typeof(elm) __res = NULL; \
00766    if ((head)->first == (elm)) {             \
00767       __res = (head)->first;                      \
00768       (head)->first = (elm)->field.next;        \
00769       if ((head)->last == (elm))       \
00770          (head)->last = NULL;       \
00771    } else {                      \
00772       typeof(elm) curelm = (head)->first;       \
00773       while (curelm && (curelm->field.next != (elm)))       \
00774          curelm = curelm->field.next;        \
00775       if (curelm) { \
00776          __res = (elm); \
00777          curelm->field.next = (elm)->field.next;         \
00778          if ((head)->last == (elm))          \
00779             (head)->last = curelm;           \
00780       } \
00781    }                       \
00782    (elm)->field.next = NULL;                                       \
00783    (__res); \
00784 })
00785 
00786 #define AST_RWLIST_REMOVE AST_LIST_REMOVE
00787 
00788 #endif /* _ASTERISK_LINKEDLISTS_H */

Generated on Wed Oct 14 15:01:56 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7