Wed Aug 7 17:15:42 2019

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

Generated on 7 Aug 2019 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1