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 non-zero if the list has entries 00447 * \return 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 ) 00540 00541 #define AST_RWLIST_TRAVERSE_SAFE_BEGIN AST_LIST_TRAVERSE_SAFE_BEGIN 00542 00543 /*! 00544 * \brief Removes the \a current entry from a list during a traversal. 00545 * \param field This is the name of the field (declared using AST_LIST_ENTRY()) 00546 * used to link entries of this list together. 00547 * 00548 * \note This macro can \b only be used inside an AST_LIST_TRAVERSE_SAFE_BEGIN() 00549 * block; it is used to unlink the current entry from the list without affecting 00550 * the list traversal (and without having to re-traverse the list to modify the 00551 * previous entry, if any). 00552 */ 00553 #define AST_LIST_REMOVE_CURRENT(field) do { \ 00554 __new_prev->field.next = NULL; \ 00555 __new_prev = __list_prev; \ 00556 if (__list_prev) \ 00557 __list_prev->field.next = __list_next; \ 00558 else \ 00559 __list_head->first = __list_next; \ 00560 if (!__list_next) \ 00561 __list_head->last = __list_prev; \ 00562 } while (0) 00563 00564 #define AST_RWLIST_REMOVE_CURRENT AST_LIST_REMOVE_CURRENT 00565 00566 #define AST_LIST_MOVE_CURRENT(newhead, field) do { \ 00567 typeof ((newhead)->first) __list_cur = __new_prev; \ 00568 AST_LIST_REMOVE_CURRENT(field); \ 00569 AST_LIST_INSERT_TAIL((newhead), __list_cur, field); \ 00570 } while (0) 00571 00572 #define AST_RWLIST_MOVE_CURRENT AST_LIST_MOVE_CURRENT 00573 00574 /*! 00575 * \brief Inserts a list entry before the current entry during a traversal. 00576 * \param elm This is a pointer to the entry to be inserted. 00577 * \param field This is the name of the field (declared using AST_LIST_ENTRY()) 00578 * used to link entries of this list together. 00579 * 00580 * \note This macro can \b only be used inside an AST_LIST_TRAVERSE_SAFE_BEGIN() 00581 * block. 00582 */ 00583 #define AST_LIST_INSERT_BEFORE_CURRENT(elm, field) do { \ 00584 if (__list_prev) { \ 00585 (elm)->field.next = __list_prev->field.next; \ 00586 __list_prev->field.next = elm; \ 00587 } else { \ 00588 (elm)->field.next = __list_head->first; \ 00589 __list_head->first = (elm); \ 00590 } \ 00591 __new_prev = (elm); \ 00592 } while (0) 00593 00594 #define AST_RWLIST_INSERT_BEFORE_CURRENT AST_LIST_INSERT_BEFORE_CURRENT 00595 00596 /*! 00597 * \brief Closes a safe loop traversal block. 00598 */ 00599 #define AST_LIST_TRAVERSE_SAFE_END } 00600 00601 #define AST_RWLIST_TRAVERSE_SAFE_END AST_LIST_TRAVERSE_SAFE_END 00602 00603 /*! 00604 * \brief Initializes a list head structure. 00605 * \param head This is a pointer to the list head structure 00606 * 00607 * This macro initializes a list head structure by setting the head 00608 * entry to \a NULL (empty list) and recreating the embedded lock. 00609 */ 00610 #define AST_LIST_HEAD_INIT(head) { \ 00611 (head)->first = NULL; \ 00612 (head)->last = NULL; \ 00613 ast_mutex_init(&(head)->lock); \ 00614 } 00615 00616 /*! 00617 * \brief Initializes an rwlist head structure. 00618 * \param head This is a pointer to the list head structure 00619 * 00620 * This macro initializes a list head structure by setting the head 00621 * entry to \a NULL (empty list) and recreating the embedded lock. 00622 */ 00623 #define AST_RWLIST_HEAD_INIT(head) { \ 00624 (head)->first = NULL; \ 00625 (head)->last = NULL; \ 00626 ast_rwlock_init(&(head)->lock); \ 00627 } 00628 00629 /*! 00630 * \brief Destroys a list head structure. 00631 * \param head This is a pointer to the list head structure 00632 * 00633 * This macro destroys a list head structure by setting the head 00634 * entry to \a NULL (empty list) and destroying the embedded lock. 00635 * It does not free the structure from memory. 00636 */ 00637 #define AST_LIST_HEAD_DESTROY(head) { \ 00638 (head)->first = NULL; \ 00639 (head)->last = NULL; \ 00640 ast_mutex_destroy(&(head)->lock); \ 00641 } 00642 00643 /*! 00644 * \brief Destroys an rwlist head structure. 00645 * \param head This is a pointer to the list head structure 00646 * 00647 * This macro destroys a list head structure by setting the head 00648 * entry to \a NULL (empty list) and destroying the embedded lock. 00649 * It does not free the structure from memory. 00650 */ 00651 #define AST_RWLIST_HEAD_DESTROY(head) { \ 00652 (head)->first = NULL; \ 00653 (head)->last = NULL; \ 00654 ast_rwlock_destroy(&(head)->lock); \ 00655 } 00656 00657 /*! 00658 * \brief Initializes a list head structure. 00659 * \param head This is a pointer to the list head structure 00660 * 00661 * This macro initializes a list head structure by setting the head 00662 * entry to \a NULL (empty list). There is no embedded lock handling 00663 * with this macro. 00664 */ 00665 #define AST_LIST_HEAD_INIT_NOLOCK(head) { \ 00666 (head)->first = NULL; \ 00667 (head)->last = NULL; \ 00668 } 00669 00670 /*! 00671 * \brief Inserts a list entry after a given entry. 00672 * \param head This is a pointer to the list head structure 00673 * \param listelm This is a pointer to the entry after which the new entry should 00674 * be inserted. 00675 * \param elm This is a pointer to the entry to be inserted. 00676 * \param field This is the name of the field (declared using AST_LIST_ENTRY()) 00677 * used to link entries of this list together. 00678 */ 00679 #define AST_LIST_INSERT_AFTER(head, listelm, elm, field) do { \ 00680 (elm)->field.next = (listelm)->field.next; \ 00681 (listelm)->field.next = (elm); \ 00682 if ((head)->last == (listelm)) \ 00683 (head)->last = (elm); \ 00684 } while (0) 00685 00686 #define AST_RWLIST_INSERT_AFTER AST_LIST_INSERT_AFTER 00687 00688 /*! 00689 * \brief Inserts a list entry at the head of a list. 00690 * \param head This is a pointer to the list head structure 00691 * \param elm This is a pointer to the entry to be inserted. 00692 * \param field This is the name of the field (declared using AST_LIST_ENTRY()) 00693 * used to link entries of this list together. 00694 */ 00695 #define AST_LIST_INSERT_HEAD(head, elm, field) do { \ 00696 (elm)->field.next = (head)->first; \ 00697 (head)->first = (elm); \ 00698 if (!(head)->last) \ 00699 (head)->last = (elm); \ 00700 } while (0) 00701 00702 #define AST_RWLIST_INSERT_HEAD AST_LIST_INSERT_HEAD 00703 00704 /*! 00705 * \brief Appends a list entry to the tail of a list. 00706 * \param head This is a pointer to the list head structure 00707 * \param elm This is a pointer to the entry to be appended. 00708 * \param field This is the name of the field (declared using AST_LIST_ENTRY()) 00709 * used to link entries of this list together. 00710 * 00711 * Note: The link field in the appended entry is \b not modified, so if it is 00712 * actually the head of a list itself, the entire list will be appended 00713 * temporarily (until the next AST_LIST_INSERT_TAIL is performed). 00714 */ 00715 #define AST_LIST_INSERT_TAIL(head, elm, field) do { \ 00716 if (!(head)->first) { \ 00717 (head)->first = (elm); \ 00718 (head)->last = (elm); \ 00719 } else { \ 00720 (head)->last->field.next = (elm); \ 00721 (head)->last = (elm); \ 00722 } \ 00723 } while (0) 00724 00725 #define AST_RWLIST_INSERT_TAIL AST_LIST_INSERT_TAIL 00726 00727 /*! 00728 * \brief Inserts a list entry into a alphabetically sorted list 00729 * \param head Pointer to the list head structure 00730 * \param elm Pointer to the entry to be inserted 00731 * \param field Name of the list entry field (declared using AST_LIST_ENTRY()) 00732 * \param sortfield Name of the field on which the list is sorted 00733 * \since 1.6.1 00734 */ 00735 #define AST_LIST_INSERT_SORTALPHA(head, elm, field, sortfield) do { \ 00736 if (!(head)->first) { \ 00737 (head)->first = (elm); \ 00738 (head)->last = (elm); \ 00739 } else { \ 00740 typeof((head)->first) cur = (head)->first, prev = NULL; \ 00741 while (cur && strcmp(cur->sortfield, elm->sortfield) < 0) { \ 00742 prev = cur; \ 00743 cur = cur->field.next; \ 00744 } \ 00745 if (!prev) { \ 00746 AST_LIST_INSERT_HEAD(head, elm, field); \ 00747 } else if (!cur) { \ 00748 AST_LIST_INSERT_TAIL(head, elm, field); \ 00749 } else { \ 00750 AST_LIST_INSERT_AFTER(head, prev, elm, field); \ 00751 } \ 00752 } \ 00753 } while (0) 00754 00755 #define AST_RWLIST_INSERT_SORTALPHA AST_LIST_INSERT_SORTALPHA 00756 00757 /*! 00758 * \brief Appends a whole list to the tail of a list. 00759 * \param head This is a pointer to the list head structure 00760 * \param list This is a pointer to the list to be appended. 00761 * \param field This is the name of the field (declared using AST_LIST_ENTRY()) 00762 * used to link entries of this list together. 00763 * 00764 * Note: The source list (the \a list parameter) will be empty after 00765 * calling this macro (the list entries are \b moved to the target list). 00766 */ 00767 #define AST_LIST_APPEND_LIST(head, list, field) do { \ 00768 if (!(head)->first) { \ 00769 (head)->first = (list)->first; \ 00770 (head)->last = (list)->last; \ 00771 } else { \ 00772 (head)->last->field.next = (list)->first; \ 00773 (head)->last = (list)->last; \ 00774 } \ 00775 (list)->first = NULL; \ 00776 (list)->last = NULL; \ 00777 } while (0) 00778 00779 #define AST_RWLIST_APPEND_LIST AST_LIST_APPEND_LIST 00780 00781 /*! 00782 * \brief Removes and returns the head entry from a list. 00783 * \param head This is a pointer to the list head structure 00784 * \param field This is the name of the field (declared using AST_LIST_ENTRY()) 00785 * used to link entries of this list together. 00786 * 00787 * Removes the head entry from the list, and returns a pointer to it. 00788 * This macro is safe to call on an empty list. 00789 */ 00790 #define AST_LIST_REMOVE_HEAD(head, field) ({ \ 00791 typeof((head)->first) cur = (head)->first; \ 00792 if (cur) { \ 00793 (head)->first = cur->field.next; \ 00794 cur->field.next = NULL; \ 00795 if ((head)->last == cur) \ 00796 (head)->last = NULL; \ 00797 } \ 00798 cur; \ 00799 }) 00800 00801 #define AST_RWLIST_REMOVE_HEAD AST_LIST_REMOVE_HEAD 00802 00803 /*! 00804 * \brief Removes a specific entry from a list. 00805 * \param head This is a pointer to the list head structure 00806 * \param elm This is a pointer to the entry to be removed. 00807 * \param field This is the name of the field (declared using AST_LIST_ENTRY()) 00808 * used to link entries of this list together. 00809 * \warning The removed entry is \b not freed nor modified in any way. 00810 */ 00811 #define AST_LIST_REMOVE(head, elm, field) ({ \ 00812 __typeof(elm) __res = NULL; \ 00813 if ((head)->first == (elm)) { \ 00814 __res = (head)->first; \ 00815 (head)->first = (elm)->field.next; \ 00816 if ((head)->last == (elm)) \ 00817 (head)->last = NULL; \ 00818 } else { \ 00819 typeof(elm) curelm = (head)->first; \ 00820 while (curelm && (curelm->field.next != (elm))) \ 00821 curelm = curelm->field.next; \ 00822 if (curelm) { \ 00823 __res = (elm); \ 00824 curelm->field.next = (elm)->field.next; \ 00825 if ((head)->last == (elm)) \ 00826 (head)->last = curelm; \ 00827 } \ 00828 } \ 00829 (elm)->field.next = NULL; \ 00830 (__res); \ 00831 }) 00832 00833 #define AST_RWLIST_REMOVE AST_LIST_REMOVE 00834 00835 #endif /* _ASTERISK_LINKEDLISTS_H */