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 non-zero on success, 0 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 non-zero on success, 0 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 non-zero on success, 0 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 non-zero on success, 0 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 non-zero on success, 0 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 non-zero on success, 0 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 AST_RWLOCK_INIT_VALUE 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) \ 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 00526 #define AST_RWLIST_REMOVE_CURRENT AST_LIST_REMOVE_CURRENT 00527 00528 /*! 00529 \brief Inserts a list entry before the current entry during a traversal. 00530 \param head This is a pointer to the list head structure 00531 \param elm This is a pointer to the entry to be inserted. 00532 \param field This is the name of the field (declared using AST_LIST_ENTRY()) 00533 used to link entries of this list together. 00534 00535 \note This macro can \b only be used inside an AST_LIST_TRAVERSE_SAFE_BEGIN() 00536 block. 00537 */ 00538 #define AST_LIST_INSERT_BEFORE_CURRENT(head, elm, field) do { \ 00539 if (__list_prev) { \ 00540 (elm)->field.next = __list_prev->field.next; \ 00541 __list_prev->field.next = elm; \ 00542 } else { \ 00543 (elm)->field.next = (head)->first; \ 00544 (head)->first = (elm); \ 00545 } \ 00546 __new_prev = (elm); \ 00547 } while (0) 00548 00549 #define AST_RWLIST_INSERT_BEFORE_CURRENT AST_LIST_INSERT_BEFORE_CURRENT 00550 00551 /*! 00552 \brief Closes a safe loop traversal block. 00553 */ 00554 #define AST_LIST_TRAVERSE_SAFE_END } 00555 00556 #define AST_RWLIST_TRAVERSE_SAFE_END AST_LIST_TRAVERSE_SAFE_END 00557 00558 /*! 00559 \brief Initializes a list head structure. 00560 \param head This is a pointer to the list head structure 00561 00562 This macro initializes a list head structure by setting the head 00563 entry to \a NULL (empty list) and recreating the embedded lock. 00564 */ 00565 #define AST_LIST_HEAD_INIT(head) { \ 00566 (head)->first = NULL; \ 00567 (head)->last = NULL; \ 00568 ast_mutex_init(&(head)->lock); \ 00569 } 00570 00571 /*! 00572 \brief Initializes an rwlist head structure. 00573 \param head This is a pointer to the list head structure 00574 00575 This macro initializes a list head structure by setting the head 00576 entry to \a NULL (empty list) and recreating the embedded lock. 00577 */ 00578 #define AST_RWLIST_HEAD_INIT(head) { \ 00579 (head)->first = NULL; \ 00580 (head)->last = NULL; \ 00581 ast_rwlock_init(&(head)->lock); \ 00582 } 00583 00584 /*! 00585 \brief Destroys a list head structure. 00586 \param head This is a pointer to the list head structure 00587 00588 This macro destroys a list head structure by setting the head 00589 entry to \a NULL (empty list) and destroying the embedded lock. 00590 It does not free the structure from memory. 00591 */ 00592 #define AST_LIST_HEAD_DESTROY(head) { \ 00593 (head)->first = NULL; \ 00594 (head)->last = NULL; \ 00595 ast_mutex_destroy(&(head)->lock); \ 00596 } 00597 00598 /*! 00599 \brief Destroys an rwlist head structure. 00600 \param head This is a pointer to the list head structure 00601 00602 This macro destroys a list head structure by setting the head 00603 entry to \a NULL (empty list) and destroying the embedded lock. 00604 It does not free the structure from memory. 00605 */ 00606 #define AST_RWLIST_HEAD_DESTROY(head) { \ 00607 (head)->first = NULL; \ 00608 (head)->last = NULL; \ 00609 ast_rwlock_destroy(&(head)->lock); \ 00610 } 00611 00612 /*! 00613 \brief Initializes a list head structure. 00614 \param head This is a pointer to the list head structure 00615 00616 This macro initializes a list head structure by setting the head 00617 entry to \a NULL (empty list). There is no embedded lock handling 00618 with this macro. 00619 */ 00620 #define AST_LIST_HEAD_INIT_NOLOCK(head) { \ 00621 (head)->first = NULL; \ 00622 (head)->last = NULL; \ 00623 } 00624 00625 /*! 00626 \brief Inserts a list entry after a given entry. 00627 \param head This is a pointer to the list head structure 00628 \param listelm This is a pointer to the entry after which the new entry should 00629 be inserted. 00630 \param elm This is a pointer to the entry to be inserted. 00631 \param field This is the name of the field (declared using AST_LIST_ENTRY()) 00632 used to link entries of this list together. 00633 */ 00634 #define AST_LIST_INSERT_AFTER(head, listelm, elm, field) do { \ 00635 (elm)->field.next = (listelm)->field.next; \ 00636 (listelm)->field.next = (elm); \ 00637 if ((head)->last == (listelm)) \ 00638 (head)->last = (elm); \ 00639 } while (0) 00640 00641 #define AST_RWLIST_INSERT_AFTER AST_LIST_INSERT_AFTER 00642 00643 /*! 00644 \brief Inserts a list entry at the head of a list. 00645 \param head This is a pointer to the list head structure 00646 \param elm This is a pointer to the entry to be inserted. 00647 \param field This is the name of the field (declared using AST_LIST_ENTRY()) 00648 used to link entries of this list together. 00649 */ 00650 #define AST_LIST_INSERT_HEAD(head, elm, field) do { \ 00651 (elm)->field.next = (head)->first; \ 00652 (head)->first = (elm); \ 00653 if (!(head)->last) \ 00654 (head)->last = (elm); \ 00655 } while (0) 00656 00657 #define AST_RWLIST_INSERT_HEAD AST_LIST_INSERT_HEAD 00658 00659 /*! 00660 \brief Appends a list entry to the tail of a list. 00661 \param head This is a pointer to the list head structure 00662 \param elm This is a pointer to the entry to be appended. 00663 \param field This is the name of the field (declared using AST_LIST_ENTRY()) 00664 used to link entries of this list together. 00665 00666 Note: The link field in the appended entry is \b not modified, so if it is 00667 actually the head of a list itself, the entire list will be appended 00668 temporarily (until the next AST_LIST_INSERT_TAIL is performed). 00669 */ 00670 #define AST_LIST_INSERT_TAIL(head, elm, field) do { \ 00671 if (!(head)->first) { \ 00672 (head)->first = (elm); \ 00673 (head)->last = (elm); \ 00674 } else { \ 00675 (head)->last->field.next = (elm); \ 00676 (head)->last = (elm); \ 00677 } \ 00678 } while (0) 00679 00680 #define AST_RWLIST_INSERT_TAIL AST_LIST_INSERT_TAIL 00681 00682 /*! 00683 \brief Appends a whole list to the tail of a list. 00684 \param head This is a pointer to the list head structure 00685 \param list This is a pointer to the list to be appended. 00686 \param field This is the name of the field (declared using AST_LIST_ENTRY()) 00687 used to link entries of this list together. 00688 */ 00689 #define AST_LIST_APPEND_LIST(head, list, field) do { \ 00690 if (!(head)->first) { \ 00691 (head)->first = (list)->first; \ 00692 (head)->last = (list)->last; \ 00693 } else { \ 00694 (head)->last->field.next = (list)->first; \ 00695 (head)->last = (list)->last; \ 00696 } \ 00697 } while (0) 00698 00699 #define AST_RWLIST_APPEND_LIST AST_LIST_APPEND_LIST 00700 00701 /*! 00702 \brief Removes and returns the head entry from a list. 00703 \param head This is a pointer to the list head structure 00704 \param field This is the name of the field (declared using AST_LIST_ENTRY()) 00705 used to link entries of this list together. 00706 00707 Removes the head entry from the list, and returns a pointer to it. 00708 This macro is safe to call on an empty list. 00709 */ 00710 #define AST_LIST_REMOVE_HEAD(head, field) ({ \ 00711 typeof((head)->first) cur = (head)->first; \ 00712 if (cur) { \ 00713 (head)->first = cur->field.next; \ 00714 cur->field.next = NULL; \ 00715 if ((head)->last == cur) \ 00716 (head)->last = NULL; \ 00717 } \ 00718 cur; \ 00719 }) 00720 00721 #define AST_RWLIST_REMOVE_HEAD AST_LIST_REMOVE_HEAD 00722 00723 /*! 00724 \brief Removes a specific entry from a list. 00725 \param head This is a pointer to the list head structure 00726 \param elm This is a pointer to the entry to be removed. 00727 \param field This is the name of the field (declared using AST_LIST_ENTRY()) 00728 used to link entries of this list together. 00729 \warning The removed entry is \b not freed nor modified in any way. 00730 */ 00731 #define AST_LIST_REMOVE(head, elm, field) do { \ 00732 if ((head)->first == (elm)) { \ 00733 (head)->first = (elm)->field.next; \ 00734 if ((head)->last == (elm)) \ 00735 (head)->last = NULL; \ 00736 } else { \ 00737 typeof(elm) curelm = (head)->first; \ 00738 while (curelm && (curelm->field.next != (elm))) \ 00739 curelm = curelm->field.next; \ 00740 if (curelm) { \ 00741 curelm->field.next = (elm)->field.next; \ 00742 if ((head)->last == (elm)) \ 00743 (head)->last = curelm; \ 00744 } \ 00745 } \ 00746 (elm)->field.next = NULL; \ 00747 } while (0) 00748 00749 #define AST_RWLIST_REMOVE AST_LIST_REMOVE 00750 00751 #endif /* _ASTERISK_LINKEDLISTS_H */