Asterisk - The Open Source Telephony Project GIT-master-67613d1
linkedlists.h
Go to the documentation of this file.
1/*
2 * Asterisk -- An open source telephony toolkit.
3 *
4 * Copyright (C) 1999 - 2006, Digium, Inc.
5 *
6 * Mark Spencer <markster@digium.com>
7 * Kevin P. Fleming <kpfleming@digium.com>
8 *
9 * See http://www.asterisk.org for more information about
10 * the Asterisk project. Please do not directly contact
11 * any of the maintainers of this project for assistance;
12 * the project provides a web site, mailing lists and IRC
13 * channels for your use.
14 *
15 * This program is free software, distributed under the terms of
16 * the GNU General Public License Version 2. See the LICENSE file
17 * at the top of the source tree.
18 */
19
20#ifndef ASTERISK_LINKEDLISTS_H
21#define ASTERISK_LINKEDLISTS_H
22
23#include "asterisk/lock.h"
24
25/*!
26 * \file
27 *
28 * \brief A set of macros to manage forward-linked lists.
29 */
30
31/*!
32 * \brief Locks a list.
33 * \param head This is a pointer to the list head structure
34 *
35 * This macro attempts to place an exclusive lock in the
36 * list head structure pointed to by head.
37 * \retval 0 on success
38 * \retval non-zero on failure
39 */
40#define AST_LIST_LOCK(head) \
41 ast_mutex_lock(&(head)->lock)
42
43/*!
44 * \brief Write locks a list.
45 * \param head This is a pointer to the list head structure
46 *
47 * This macro attempts to place an exclusive write lock in the
48 * list head structure pointed to by head.
49 * \retval 0 on success
50 * \retval non-zero on failure
51 */
52#define AST_RWLIST_WRLOCK(head) \
53 ast_rwlock_wrlock(&(head)->lock)
54
55/*!
56 * \brief Write locks a list, with timeout.
57 * \param head This is a pointer to the list head structure
58 * \param ts Pointer to a timespec structure
59 *
60 * This macro attempts to place an exclusive write lock in the
61 * list head structure pointed to by head.
62 * \retval 0 on success
63 * \retval non-zero on failure
64 *
65 * \since 1.6.1
66 */
67#define AST_RWLIST_TIMEDWRLOCK(head, ts) ast_rwlock_timedwrlock(&(head)->lock, ts)
68
69/*!
70 * \brief Read locks a list.
71 * \param head This is a pointer to the list head structure
72 *
73 * This macro attempts to place a read lock in the
74 * list head structure pointed to by head.
75 * \retval 0 on success
76 * \retval non-zero on failure
77 */
78#define AST_RWLIST_RDLOCK(head) \
79 ast_rwlock_rdlock(&(head)->lock)
80
81/*!
82 * \brief Read locks a list, with timeout.
83 * \param head This is a pointer to the list head structure
84 * \param ts Pointer to a timespec structure
85 *
86 * This macro attempts to place a read lock in the
87 * list head structure pointed to by head.
88 * \retval 0 on success
89 * \retval non-zero on failure
90 *
91 * \since 1.6.1
92 */
93#define AST_RWLIST_TIMEDRDLOCK(head, ts) \
94 ast_rwlock_timedrdlock(&(head)->lock, ts)
95
96/*!
97 * \brief Locks a list, without blocking if the list is locked.
98 * \param head This is a pointer to the list head structure
99 *
100 * This macro attempts to place an exclusive lock in the
101 * list head structure pointed to by head.
102 * \retval 0 on success
103 * \retval non-zero on failure
104 */
105#define AST_LIST_TRYLOCK(head) \
106 ast_mutex_trylock(&(head)->lock)
107
108/*!
109 * \brief Write locks a list, without blocking if the list is locked.
110 * \param head This is a pointer to the list head structure
111 *
112 * This macro attempts to place an exclusive write lock in the
113 * list head structure pointed to by head.
114 * \retval 0 on success
115 * \retval non-zero on failure
116 */
117#define AST_RWLIST_TRYWRLOCK(head) \
118 ast_rwlock_trywrlock(&(head)->lock)
119
120/*!
121 * \brief Read locks a list, without blocking if the list is locked.
122 * \param head This is a pointer to the list head structure
123 *
124 * This macro attempts to place a read lock in the
125 * list head structure pointed to by head.
126 * \retval 0 on success
127 * \retval non-zero on failure
128 */
129#define AST_RWLIST_TRYRDLOCK(head) \
130 ast_rwlock_tryrdlock(&(head)->lock)
131
132/*!
133 * \brief Attempts to unlock a list.
134 * \param head This is a pointer to the list head structure
135 *
136 * This macro attempts to remove an exclusive lock from the
137 * list head structure pointed to by head. If the list
138 * was not locked by this thread, this macro has no effect.
139 */
140#define AST_LIST_UNLOCK(head) \
141 ast_mutex_unlock(&(head)->lock)
142
143/*!
144 * \brief Attempts to unlock a read/write based list.
145 * \param head This is a pointer to the list head structure
146 *
147 * This macro attempts to remove a read or write lock from the
148 * list head structure pointed to by head. If the list
149 * was not locked by this thread, this macro has no effect.
150 */
151#define AST_RWLIST_UNLOCK(head) \
152 ast_rwlock_unlock(&(head)->lock)
153
154/*!
155 * \brief Defines a structure to be used to hold a list of specified type.
156 * \param name This will be the name of the defined structure.
157 * \param type This is the type of each list entry.
158 *
159 * This macro creates a structure definition that can be used
160 * to hold a list of the entries of type \a type. It does not actually
161 * declare (allocate) a structure; to do that, either follow this
162 * macro with the desired name of the instance you wish to declare,
163 * or use the specified \a name to declare instances elsewhere.
164 *
165 * Example usage:
166 * \code
167 * static AST_LIST_HEAD(entry_list, entry) entries;
168 * \endcode
169 *
170 * This would define \c struct \c entry_list, and declare an instance of it named
171 * \a entries, all intended to hold a list of type \c struct \c entry.
172 */
173#define AST_LIST_HEAD(name, type) \
174struct name { \
175 struct type *first; \
176 struct type *last; \
177 ast_mutex_t lock; \
178}
179
180/*!
181 * \brief Defines a structure to be used to hold a read/write list of specified type.
182 * \param name This will be the name of the defined structure.
183 * \param type This is the type of each list entry.
184 *
185 * This macro creates a structure definition that can be used
186 * to hold a list of the entries of type \a type. It does not actually
187 * declare (allocate) a structure; to do that, either follow this
188 * macro with the desired name of the instance you wish to declare,
189 * or use the specified \a name to declare instances elsewhere.
190 *
191 * Example usage:
192 * \code
193 * static AST_RWLIST_HEAD(entry_list, entry) entries;
194 * \endcode
195 *
196 * This would define \c struct \c entry_list, and declare an instance of it named
197 * \a entries, all intended to hold a list of type \c struct \c entry.
198 */
199#define AST_RWLIST_HEAD(name, type) \
200struct name { \
201 struct type *first; \
202 struct type *last; \
203 ast_rwlock_t lock; \
204}
205
206/*!
207 * \brief Defines a structure to be used to hold a list of specified type (with no lock).
208 * \param name This will be the name of the defined structure.
209 * \param type This is the type of each list entry.
210 *
211 * This macro creates a structure definition that can be used
212 * to hold a list of the entries of type \a type. It does not actually
213 * declare (allocate) a structure; to do that, either follow this
214 * macro with the desired name of the instance you wish to declare,
215 * or use the specified \a name to declare instances elsewhere.
216 *
217 * Example usage:
218 * \code
219 * static AST_LIST_HEAD_NOLOCK(entry_list, entry) entries;
220 * \endcode
221 *
222 * This would define \c struct \c entry_list, and declare an instance of it named
223 * \a entries, all intended to hold a list of type \c struct \c entry.
224 */
225#define AST_LIST_HEAD_NOLOCK(name, type) \
226struct name { \
227 struct type *first; \
228 struct type *last; \
229}
230
231/*!
232 * \brief Defines initial values for a declaration of AST_LIST_HEAD
233 */
234#define AST_LIST_HEAD_INIT_VALUE { \
235 .first = NULL, \
236 .last = NULL, \
237 .lock = AST_MUTEX_INIT_VALUE, \
238 }
239
240/*!
241 * \brief Defines initial values for a declaration of AST_RWLIST_HEAD
242 */
243#define AST_RWLIST_HEAD_INIT_VALUE { \
244 .first = NULL, \
245 .last = NULL, \
246 .lock = AST_RWLOCK_INIT_VALUE, \
247 }
248
249/*!
250 * \brief Defines initial values for a declaration of AST_LIST_HEAD_NOLOCK
251 */
252#define AST_LIST_HEAD_NOLOCK_INIT_VALUE { \
253 .first = NULL, \
254 .last = NULL, \
255 }
256
257/*!
258 * \brief Defines a structure to be used to hold a list of specified type, statically initialized.
259 * \param name This will be the name of the defined structure.
260 * \param type This is the type of each list entry.
261 *
262 * This macro creates a structure definition that can be used
263 * to hold a list of the entries of type \a type, and allocates an instance
264 * of it, initialized to be empty.
265 *
266 * Example usage:
267 * \code
268 * static AST_LIST_HEAD_STATIC(entry_list, entry);
269 * \endcode
270 *
271 * This would define \c struct \c entry_list, intended to hold a list of
272 * type \c struct \c entry.
273 */
274#if defined(AST_MUTEX_INIT_W_CONSTRUCTORS)
275#define AST_LIST_HEAD_STATIC(name, type) \
276struct name { \
277 struct type *first; \
278 struct type *last; \
279 ast_mutex_t lock; \
280} name; \
281static void __attribute__((constructor)) __init_##name(void) \
282{ \
283 AST_LIST_HEAD_INIT(&name); \
284} \
285static void __attribute__((destructor)) __fini_##name(void) \
286{ \
287 AST_LIST_HEAD_DESTROY(&name); \
288} \
289struct __dummy_##name
290#else
291#define AST_LIST_HEAD_STATIC(name, type) \
292struct name { \
293 struct type *first; \
294 struct type *last; \
295 ast_mutex_t lock; \
296} name = AST_LIST_HEAD_INIT_VALUE
297#endif
298
299/*!
300 * \brief Defines a structure to be used to hold a read/write list of specified type, statically initialized.
301 * \param name This will be the name of the defined structure.
302 * \param type This is the type of each list entry.
303 *
304 * This macro creates a structure definition that can be used
305 * to hold a list of the entries of type \a type, and allocates an instance
306 * of it, initialized to be empty.
307 *
308 * Example usage:
309 * \code
310 * static AST_RWLIST_HEAD_STATIC(entry_list, entry);
311 * \endcode
312 *
313 * This would define \c struct \c entry_list, intended to hold a list of
314 * type \c struct \c entry.
315 */
316#ifndef HAVE_PTHREAD_RWLOCK_INITIALIZER
317#define AST_RWLIST_HEAD_STATIC(name, type) \
318struct name { \
319 struct type *first; \
320 struct type *last; \
321 ast_rwlock_t lock; \
322} name; \
323static void __attribute__((constructor)) __init_##name(void) \
324{ \
325 AST_RWLIST_HEAD_INIT(&name); \
326} \
327static void __attribute__((destructor)) __fini_##name(void) \
328{ \
329 AST_RWLIST_HEAD_DESTROY(&name); \
330} \
331struct __dummy_##name
332#else
333#define AST_RWLIST_HEAD_STATIC(name, type) \
334struct name { \
335 struct type *first; \
336 struct type *last; \
337 ast_rwlock_t lock; \
338} name = AST_RWLIST_HEAD_INIT_VALUE
339#endif
340
341/*!
342 * \brief Defines a structure to be used to hold a list of specified type, statically initialized.
343 *
344 * This is the same as AST_LIST_HEAD_STATIC, except without the lock included.
345 */
346#define AST_LIST_HEAD_NOLOCK_STATIC(name, type) \
347struct name { \
348 struct type *first; \
349 struct type *last; \
350} name = AST_LIST_HEAD_NOLOCK_INIT_VALUE
351
352/*!
353 * \brief Initializes a list head structure with a specified first entry.
354 * \param head This is a pointer to the list head structure
355 * \param entry pointer to the list entry that will become the head of the list
356 *
357 * This macro initializes a list head structure by setting the head
358 * entry to the supplied value and recreating the embedded lock.
359 */
360#define AST_LIST_HEAD_SET(head, entry) do { \
361 (head)->first = (entry); \
362 (head)->last = (entry); \
363 ast_mutex_init(&(head)->lock); \
364} while (0)
365
366/*!
367 * \brief Initializes an rwlist head structure with a specified first entry.
368 * \param head This is a pointer to the list head structure
369 * \param entry pointer to the list entry that will become the head of the list
370 *
371 * This macro initializes a list head structure by setting the head
372 * entry to the supplied value and recreating the embedded lock.
373 */
374#define AST_RWLIST_HEAD_SET(head, entry) do { \
375 (head)->first = (entry); \
376 (head)->last = (entry); \
377 ast_rwlock_init(&(head)->lock); \
378} while (0)
379
380/*!
381 * \brief Initializes a list head structure with a specified first entry.
382 * \param head This is a pointer to the list head structure
383 * \param entry pointer to the list entry that will become the head of the list
384 *
385 * This macro initializes a list head structure by setting the head
386 * entry to the supplied value.
387 */
388#define AST_LIST_HEAD_SET_NOLOCK(head, entry) do { \
389 (head)->first = (entry); \
390 (head)->last = (entry); \
391} while (0)
392
393/*!
394 * \brief Declare a forward link structure inside a list entry.
395 * \param type This is the type of each list entry.
396 *
397 * This macro declares a structure to be used to link list entries together.
398 * It must be used inside the definition of the structure named in
399 * \a type, as follows:
400 *
401 * \code
402 * struct list_entry {
403 ...
404 AST_LIST_ENTRY(list_entry) list;
405 * }
406 * \endcode
407 *
408 * The field name \a list here is arbitrary, and can be anything you wish.
409 */
410#define AST_LIST_ENTRY(type) \
411struct { \
412 struct type *next; \
413}
414
415#define AST_RWLIST_ENTRY AST_LIST_ENTRY
416
417/*!
418 * \brief Returns the first entry contained in a list.
419 * \param head This is a pointer to the list head structure
420 */
421#define AST_LIST_FIRST(head) ((head)->first)
422
423#define AST_RWLIST_FIRST AST_LIST_FIRST
424
425/*!
426 * \brief Returns the last entry contained in a list.
427 * \param head This is a pointer to the list head structure
428 */
429#define AST_LIST_LAST(head) ((head)->last)
430
431#define AST_RWLIST_LAST AST_LIST_LAST
432
433/*!
434 * \brief Returns the next entry in the list after the given entry.
435 * \param elm This is a pointer to the current entry.
436 * \param field This is the name of the field (declared using AST_LIST_ENTRY())
437 * used to link entries of this list together.
438 */
439#define AST_LIST_NEXT(elm, field) ((elm)->field.next)
440
441#define AST_RWLIST_NEXT AST_LIST_NEXT
442
443/*!
444 * \brief Checks whether the specified list contains any entries.
445 * \param head This is a pointer to the list head structure
446 *
447 * \return zero if the list has entries
448 * \return non-zero if not.
449 */
450#define AST_LIST_EMPTY(head) (AST_LIST_FIRST(head) == NULL)
451
452#define AST_RWLIST_EMPTY AST_LIST_EMPTY
453
454/*!
455 * \brief Loops over (traverses) the entries in a list.
456 * \param head This is a pointer to the list head structure
457 * \param var This is the name of the variable that will hold a pointer to the
458 * current list entry on each iteration. It must be declared before calling
459 * this macro.
460 * \param field This is the name of the field (declared using AST_LIST_ENTRY())
461 * used to link entries of this list together.
462 *
463 * This macro is use to loop over (traverse) the entries in a list. It uses a
464 * \a for loop, and supplies the enclosed code with a pointer to each list
465 * entry as it loops. It is typically used as follows:
466 * \code
467 * static AST_LIST_HEAD(entry_list, list_entry) entries;
468 * ...
469 * struct list_entry {
470 ...
471 AST_LIST_ENTRY(list_entry) list;
472 * }
473 * ...
474 * struct list_entry *current;
475 * ...
476 * AST_LIST_TRAVERSE(&entries, current, list) {
477 (do something with current here)
478 * }
479 * \endcode
480 * \warning If you modify the forward-link pointer contained in the \a current entry while
481 * inside the loop, the behavior will be unpredictable. At a minimum, the following
482 * macros will modify the forward-link pointer, and should not be used inside
483 * AST_LIST_TRAVERSE() against the entry pointed to by the \a current pointer without
484 * careful consideration of their consequences:
485 * \li AST_LIST_NEXT() (when used as an lvalue)
486 * \li AST_LIST_INSERT_AFTER()
487 * \li AST_LIST_INSERT_HEAD()
488 * \li AST_LIST_INSERT_TAIL()
489 * \li AST_LIST_INSERT_SORTALPHA()
490 */
491#define AST_LIST_TRAVERSE(head,var,field) \
492 for((var) = (head)->first; (var); (var) = (var)->field.next)
493
494#define AST_RWLIST_TRAVERSE AST_LIST_TRAVERSE
495
496/*!
497 * \brief Loops safely over (traverses) the entries in a list.
498 * \param head This is a pointer to the list head structure
499 * \param var This is the name of the variable that will hold a pointer to the
500 * current list entry on each iteration. It must be declared before calling
501 * this macro.
502 * \param field This is the name of the field (declared using AST_LIST_ENTRY())
503 * used to link entries of this list together.
504 *
505 * This macro is used to safely loop over (traverse) the entries in a list. It
506 * uses a \a for loop, and supplies the enclosed code with a pointer to each list
507 * entry as it loops. It is typically used as follows:
508 *
509 * \code
510 * static AST_LIST_HEAD(entry_list, list_entry) entries;
511 * ...
512 * struct list_entry {
513 ...
514 AST_LIST_ENTRY(list_entry) list;
515 * }
516 * ...
517 * struct list_entry *current;
518 * ...
519 * AST_LIST_TRAVERSE_SAFE_BEGIN(&entries, current, list) {
520 (do something with current here)
521 * }
522 * AST_LIST_TRAVERSE_SAFE_END;
523 * \endcode
524 *
525 * It differs from AST_LIST_TRAVERSE() in that the code inside the loop can modify
526 * (or even free, after calling AST_LIST_REMOVE_CURRENT()) the entry pointed to by
527 * the \a current pointer without affecting the loop traversal.
528 */
529#define AST_LIST_TRAVERSE_SAFE_BEGIN(head, var, field) { \
530 typeof((head)) __list_head = head; \
531 typeof(__list_head->first) __list_next; \
532 typeof(__list_head->first) __list_prev = NULL; \
533 typeof(__list_head->first) __list_current; \
534 for ((var) = __list_head->first, \
535 __list_current = (var), \
536 __list_next = (var) ? (var)->field.next : NULL; \
537 (var); \
538 __list_prev = __list_current, \
539 (var) = __list_next, \
540 __list_current = (var), \
541 __list_next = (var) ? (var)->field.next : NULL, \
542 (void) __list_prev /* To quiet compiler? */ \
543 )
544
545#define AST_RWLIST_TRAVERSE_SAFE_BEGIN AST_LIST_TRAVERSE_SAFE_BEGIN
546
547/*!
548 * \brief Removes the \a current entry from a list during a traversal.
549 * \param field This is the name of the field (declared using AST_LIST_ENTRY())
550 * used to link entries of this list together.
551 *
552 * \note This macro can \b only be used inside an AST_LIST_TRAVERSE_SAFE_BEGIN()
553 * block; it is used to unlink the current entry from the list without affecting
554 * the list traversal (and without having to re-traverse the list to modify the
555 * previous entry, if any).
556 */
557#define AST_LIST_REMOVE_CURRENT(field) do { \
558 __list_current->field.next = NULL; \
559 __list_current = __list_prev; \
560 if (__list_prev) { \
561 __list_prev->field.next = __list_next; \
562 } else { \
563 __list_head->first = __list_next; \
564 } \
565 if (!__list_next) { \
566 __list_head->last = __list_prev; \
567 } \
568 } while (0)
569
570#define AST_RWLIST_REMOVE_CURRENT AST_LIST_REMOVE_CURRENT
571
572/*!
573 * \brief Move the current list entry to another list.
574 *
575 * \note This is a silly macro. It should be done explicitly
576 * otherwise the field parameter must be the same for the two
577 * lists.
578 *
579 * AST_LIST_REMOVE_CURRENT(field);
580 * AST_LIST_INSERT_TAIL(newhead, var, other_field);
581 */
582#define AST_LIST_MOVE_CURRENT(newhead, field) do { \
583 typeof ((newhead)->first) __extracted = __list_current; \
584 AST_LIST_REMOVE_CURRENT(field); \
585 AST_LIST_INSERT_TAIL((newhead), __extracted, field); \
586 } while (0)
587
588#define AST_RWLIST_MOVE_CURRENT AST_LIST_MOVE_CURRENT
589
590/*!
591 * \brief Inserts a list entry before the current entry during a traversal.
592 * \param elm This is a pointer to the entry to be inserted.
593 * \param field This is the name of the field (declared using AST_LIST_ENTRY())
594 * used to link entries of this list together.
595 *
596 * \note This macro can \b only be used inside an AST_LIST_TRAVERSE_SAFE_BEGIN()
597 * block.
598 */
599#define AST_LIST_INSERT_BEFORE_CURRENT(elm, field) do { \
600 if (__list_prev) { \
601 (elm)->field.next = __list_prev->field.next; \
602 __list_prev->field.next = elm; \
603 } else { \
604 (elm)->field.next = __list_head->first; \
605 __list_head->first = (elm); \
606 } \
607 __list_prev = (elm); \
608} while (0)
609
610#define AST_RWLIST_INSERT_BEFORE_CURRENT AST_LIST_INSERT_BEFORE_CURRENT
611
612/*!
613 * \brief Closes a safe loop traversal block.
614 */
615#define AST_LIST_TRAVERSE_SAFE_END }
616
617#define AST_RWLIST_TRAVERSE_SAFE_END AST_LIST_TRAVERSE_SAFE_END
618
619/*!
620 * \brief Initializes a list head structure.
621 * \param head This is a pointer to the list head structure
622 *
623 * This macro initializes a list head structure by setting the head
624 * entry to \a NULL (empty list) and recreating the embedded lock.
625 */
626#define AST_LIST_HEAD_INIT(head) { \
627 (head)->first = NULL; \
628 (head)->last = NULL; \
629 ast_mutex_init(&(head)->lock); \
630}
631
632/*!
633 * \brief Initializes an rwlist head structure.
634 * \param head This is a pointer to the list head structure
635 *
636 * This macro initializes a list head structure by setting the head
637 * entry to \a NULL (empty list) and recreating the embedded lock.
638 */
639#define AST_RWLIST_HEAD_INIT(head) { \
640 (head)->first = NULL; \
641 (head)->last = NULL; \
642 ast_rwlock_init(&(head)->lock); \
643}
644
645/*!
646 * \brief Destroys a list head structure.
647 * \param head This is a pointer to the list head structure
648 *
649 * This macro destroys a list head structure by setting the head
650 * entry to \a NULL (empty list) and destroying the embedded lock.
651 * It does not free the structure from memory.
652 */
653#define AST_LIST_HEAD_DESTROY(head) { \
654 (head)->first = NULL; \
655 (head)->last = NULL; \
656 ast_mutex_destroy(&(head)->lock); \
657}
658
659/*!
660 * \brief Destroys an rwlist head structure.
661 * \param head This is a pointer to the list head structure
662 *
663 * This macro destroys a list head structure by setting the head
664 * entry to \a NULL (empty list) and destroying the embedded lock.
665 * It does not free the structure from memory.
666 */
667#define AST_RWLIST_HEAD_DESTROY(head) { \
668 (head)->first = NULL; \
669 (head)->last = NULL; \
670 ast_rwlock_destroy(&(head)->lock); \
671}
672
673/*!
674 * \brief Initializes a list head structure.
675 * \param head This is a pointer to the list head structure
676 *
677 * This macro initializes a list head structure by setting the head
678 * entry to \a NULL (empty list). There is no embedded lock handling
679 * with this macro.
680 */
681#define AST_LIST_HEAD_INIT_NOLOCK(head) { \
682 (head)->first = NULL; \
683 (head)->last = NULL; \
684}
685
686/*!
687 * \brief Inserts a list entry after a given entry.
688 * \param head This is a pointer to the list head structure
689 * \param listelm This is a pointer to the entry after which the new entry should
690 * be inserted.
691 * \param elm This is a pointer to the entry to be inserted.
692 * \param field This is the name of the field (declared using AST_LIST_ENTRY())
693 * used to link entries of this list together.
694 */
695#define AST_LIST_INSERT_AFTER(head, listelm, elm, field) do { \
696 (elm)->field.next = (listelm)->field.next; \
697 (listelm)->field.next = (elm); \
698 if ((head)->last == (listelm)) \
699 (head)->last = (elm); \
700} while (0)
701
702#define AST_RWLIST_INSERT_AFTER AST_LIST_INSERT_AFTER
703
704/*!
705 * \brief Inserts a list entry at the head of a list.
706 * \param head This is a pointer to the list head structure
707 * \param elm This is a pointer to the entry to be inserted.
708 * \param field This is the name of the field (declared using AST_LIST_ENTRY())
709 * used to link entries of this list together.
710 */
711#define AST_LIST_INSERT_HEAD(head, elm, field) do { \
712 (elm)->field.next = (head)->first; \
713 (head)->first = (elm); \
714 if (!(head)->last) \
715 (head)->last = (elm); \
716} while (0)
717
718#define AST_RWLIST_INSERT_HEAD AST_LIST_INSERT_HEAD
719
720/*!
721 * \brief Appends a list entry to the tail of a list.
722 * \param head This is a pointer to the list head structure
723 * \param elm This is a pointer to the entry to be appended.
724 * \param field This is the name of the field (declared using AST_LIST_ENTRY())
725 * used to link entries of this list together.
726 *
727 * Note: The link field in the appended entry is \b not modified, so if it is
728 * actually the head of a list itself, the entire list will be appended
729 * temporarily (until the next AST_LIST_INSERT_TAIL is performed).
730 */
731#define AST_LIST_INSERT_TAIL(head, elm, field) do { \
732 if (!(head)->first) { \
733 (head)->first = (elm); \
734 (head)->last = (elm); \
735 } else { \
736 (head)->last->field.next = (elm); \
737 (head)->last = (elm); \
738 } \
739} while (0)
740
741#define AST_RWLIST_INSERT_TAIL AST_LIST_INSERT_TAIL
742
743/*!
744 * \brief Inserts a list entry into a alphabetically sorted list
745 * \param head Pointer to the list head structure
746 * \param elm Pointer to the entry to be inserted
747 * \param field Name of the list entry field (declared using AST_LIST_ENTRY())
748 * \param sortfield Name of the field on which the list is sorted
749 * \since 1.6.1
750 */
751#define AST_LIST_INSERT_SORTALPHA(head, elm, field, sortfield) do { \
752 if (!(head)->first) { \
753 (head)->first = (elm); \
754 (head)->last = (elm); \
755 } else { \
756 typeof((head)->first) __cur = (head)->first, __prev = NULL; \
757 while (__cur && strcmp(__cur->sortfield, elm->sortfield) < 0) { \
758 __prev = __cur; \
759 __cur = __cur->field.next; \
760 } \
761 if (!__prev) { \
762 AST_LIST_INSERT_HEAD(head, elm, field); \
763 } else if (!__cur) { \
764 AST_LIST_INSERT_TAIL(head, elm, field); \
765 } else { \
766 AST_LIST_INSERT_AFTER(head, __prev, elm, field); \
767 } \
768 } \
769} while (0)
770
771#define AST_RWLIST_INSERT_SORTALPHA AST_LIST_INSERT_SORTALPHA
772
773/*!
774 * \brief Appends a whole list to the tail of a list.
775 * \param head This is a pointer to the list head structure
776 * \param list This is a pointer to the list to be appended.
777 * \param field This is the name of the field (declared using AST_LIST_ENTRY())
778 * used to link entries of this list together.
779 *
780 * Note: The source list (the \a list parameter) will be empty after
781 * calling this macro (the list entries are \b moved to the target list).
782 */
783#define AST_LIST_APPEND_LIST(head, list, field) do { \
784 if (!(list)->first) { \
785 break; \
786 } \
787 if (!(head)->first) { \
788 (head)->first = (list)->first; \
789 (head)->last = (list)->last; \
790 } else { \
791 (head)->last->field.next = (list)->first; \
792 (head)->last = (list)->last; \
793 } \
794 (list)->first = NULL; \
795 (list)->last = NULL; \
796} while (0)
797
798#define AST_RWLIST_APPEND_LIST AST_LIST_APPEND_LIST
799
800/*!
801 \brief Inserts a whole list after a specific entry in a list
802 \param head This is a pointer to the list head structure
803 \param list This is a pointer to the list to be inserted.
804 \param elm This is a pointer to the entry after which the new list should
805 be inserted.
806 \param field This is the name of the field (declared using AST_LIST_ENTRY())
807 used to link entries of the lists together.
808
809 Note: The source list (the \a list parameter) will be empty after
810 calling this macro (the list entries are \b moved to the target list).
811 */
812#define AST_LIST_INSERT_LIST_AFTER(head, list, elm, field) do { \
813 (list)->last->field.next = (elm)->field.next; \
814 (elm)->field.next = (list)->first; \
815 if ((head)->last == elm) { \
816 (head)->last = (list)->last; \
817 } \
818 (list)->first = NULL; \
819 (list)->last = NULL; \
820} while(0)
821
822#define AST_RWLIST_INSERT_LIST_AFTER AST_LIST_INSERT_LIST_AFTER
823
824/*!
825 * \brief Removes and returns the head entry from a list.
826 * \param head This is a pointer to the list head structure
827 * \param field This is the name of the field (declared using AST_LIST_ENTRY())
828 * used to link entries of this list together.
829 *
830 * Removes the head entry from the list, and returns a pointer to it.
831 * This macro is safe to call on an empty list.
832 */
833#define AST_LIST_REMOVE_HEAD(head, field) ({ \
834 typeof((head)->first) __cur = (head)->first; \
835 if (__cur) { \
836 (head)->first = __cur->field.next; \
837 __cur->field.next = NULL; \
838 if ((head)->last == __cur) \
839 (head)->last = NULL; \
840 } \
841 __cur; \
842 })
843
844#define AST_RWLIST_REMOVE_HEAD AST_LIST_REMOVE_HEAD
845
846/*!
847 * \brief Removes a specific entry from a list.
848 * \param head This is a pointer to the list head structure
849 * \param elm This is a pointer to the entry to be removed.
850 * \param field This is the name of the field (declared using AST_LIST_ENTRY())
851 * used to link entries of this list together.
852 * \retval elm if elm was in the list.
853 * \retval NULL if elm was not in the list or elm was NULL.
854 * \warning The removed entry is \b not freed.
855 */
856#define AST_LIST_REMOVE(head, elm, field) \
857 ({ \
858 typeof(elm) __elm = (elm); \
859 if (__elm) { \
860 if ((head)->first == __elm) { \
861 (head)->first = __elm->field.next; \
862 __elm->field.next = NULL; \
863 if ((head)->last == __elm) { \
864 (head)->last = NULL; \
865 } \
866 } else { \
867 typeof(elm) __prev = (head)->first; \
868 while (__prev && __prev->field.next != __elm) { \
869 __prev = __prev->field.next; \
870 } \
871 if (__prev) { \
872 __prev->field.next = __elm->field.next; \
873 __elm->field.next = NULL; \
874 if ((head)->last == __elm) { \
875 (head)->last = __prev; \
876 } \
877 } else { \
878 __elm = NULL; \
879 } \
880 } \
881 } \
882 __elm; \
883 })
884
885#define AST_RWLIST_REMOVE AST_LIST_REMOVE
886
887#endif /* _ASTERISK_LINKEDLISTS_H */
Asterisk locking-related definitions: