git.ozlabs.org Git - ccan/blob - ccan/list/list.h

   1 /* Licensed under BSD-MIT - see LICENSE file for details */
   2 #ifndef CCAN_LIST_H
   3 #define CCAN_LIST_H
   4 //#define CCAN_LIST_DEBUG 1
   5 #include <stdbool.h>
   6 #include <assert.h>
   7 #include <ccan/str/str.h>
   8 #include <ccan/container_of/container_of.h>
   9 #include <ccan/check_type/check_type.h>
  10
  11 /**
  12  * struct list_node - an entry in a doubly-linked list
  13  * @next: next entry (self if empty)
  14  * @prev: previous entry (self if empty)
  15  *
  16  * This is used as an entry in a linked list.
  17  * Example:
  18  *      struct child {
  19  *              const char *name;
  20  *              // Linked list of all us children.
  21  *              struct list_node list;
  22  *      };
  23  */
  24 struct list_node
  25 {
  26         struct list_node *next, *prev;
  27 };
  28
  29 /**
  30  * struct list_head - the head of a doubly-linked list
  31  * @h: the list_head (containing next and prev pointers)
  32  *
  33  * This is used as the head of a linked list.
  34  * Example:
  35  *      struct parent {
  36  *              const char *name;
  37  *              struct list_head children;
  38  *              unsigned int num_children;
  39  *      };
  40  */
  41 struct list_head
  42 {
  43         struct list_node n;
  44 };
  45
  46 /**
  47  * list_check - check head of a list for consistency
  48  * @h: the list_head
  49  * @abortstr: the location to print on aborting, or NULL.
  50  *
  51  * Because list_nodes have redundant information, consistency checking between
  52  * the back and forward links can be done.  This is useful as a debugging check.
  53  * If @abortstr is non-NULL, that will be printed in a diagnostic if the list
  54  * is inconsistent, and the function will abort.
  55  *
  56  * Returns the list head if the list is consistent, NULL if not (it
  57  * can never return NULL if @abortstr is set).
  58  *
  59  * See also: list_check_node()
  60  *
  61  * Example:
  62  *      static void dump_parent(struct parent *p)
  63  *      {
  64  *              struct child *c;
  65  *
  66  *              printf("%s (%u children):\n", p->name, p->num_children);
  67  *              list_check(&p->children, "bad child list");
  68  *              list_for_each(&p->children, c, list)
  69  *                      printf(" -> %s\n", c->name);
  70  *      }
  71  */
  72 struct list_head *list_check(const struct list_head *h, const char *abortstr);
  73
  74 /**
  75  * list_check_node - check node of a list for consistency
  76  * @n: the list_node
  77  * @abortstr: the location to print on aborting, or NULL.
  78  *
  79  * Check consistency of the list node is in (it must be in one).
  80  *
  81  * See also: list_check()
  82  *
  83  * Example:
  84  *      static void dump_child(const struct child *c)
  85  *      {
  86  *              list_check_node(&c->list, "bad child list");
  87  *              printf("%s\n", c->name);
  88  *      }
  89  */
  90 struct list_node *list_check_node(const struct list_node *n,
  91                                   const char *abortstr);
  92
  93 #define LIST_LOC __FILE__  ":" stringify(__LINE__)
  94 #ifdef CCAN_LIST_DEBUG
  95 #define list_debug(h, loc) list_check((h), loc)
  96 #define list_debug_node(n, loc) list_check_node((n), loc)
  97 #else
  98 #define list_debug(h, loc) (h)
  99 #define list_debug_node(n, loc) (n)
 100 #endif
 101
 102 /**
 103  * LIST_HEAD_INIT - initializer for an empty list_head
 104  * @name: the name of the list.
 105  *
 106  * Explicit initializer for an empty list.
 107  *
 108  * See also:
 109  *      LIST_HEAD, list_head_init()
 110  *
 111  * Example:
 112  *      static struct list_head my_list = LIST_HEAD_INIT(my_list);
 113  */
 114 #define LIST_HEAD_INIT(name) { { &name.n, &name.n } }
 115
 116 /**
 117  * LIST_HEAD - define and initialize an empty list_head
 118  * @name: the name of the list.
 119  *
 120  * The LIST_HEAD macro defines a list_head and initializes it to an empty
 121  * list.  It can be prepended by "static" to define a static list_head.
 122  *
 123  * See also:
 124  *      LIST_HEAD_INIT, list_head_init()
 125  *
 126  * Example:
 127  *      static LIST_HEAD(my_global_list);
 128  */
 129 #define LIST_HEAD(name) \
 130         struct list_head name = LIST_HEAD_INIT(name)
 131
 132 /**
 133  * list_head_init - initialize a list_head
 134  * @h: the list_head to set to the empty list
 135  *
 136  * Example:
 137  *      ...
 138  *      struct parent *parent = malloc(sizeof(*parent));
 139  *
 140  *      list_head_init(&parent->children);
 141  *      parent->num_children = 0;
 142  */
 143 static inline void list_head_init(struct list_head *h)
 144 {
 145         h->n.next = h->n.prev = &h->n;
 146 }
 147
 148 /**
 149  * list_node_init - initialize a list_node
 150  * @n: the list_node to link to itself.
 151  *
 152  * You don't need to use this normally!  But it lets you list_del(@n)
 153  * safely.
 154  */
 155 static inline void list_node_init(struct list_node *n)
 156 {
 157         n->next = n->prev = n;
 158 }
 159
 160 /**
 161  * list_add - add an entry at the start of a linked list.
 162  * @h: the list_head to add the node to
 163  * @n: the list_node to add to the list.
 164  *
 165  * The list_node does not need to be initialized; it will be overwritten.
 166  * Example:
 167  *      struct child *child = malloc(sizeof(*child));
 168  *
 169  *      child->name = "marvin";
 170  *      list_add(&parent->children, &child->list);
 171  *      parent->num_children++;
 172  */
 173 #define list_add(h, n) list_add_(h, n, LIST_LOC)
 174 static inline void list_add_(struct list_head *h,
 175                              struct list_node *n,
 176                              const char *abortstr)
 177 {
 178         n->next = h->n.next;
 179         n->prev = &h->n;
 180         h->n.next->prev = n;
 181         h->n.next = n;
 182         (void)list_debug(h, abortstr);
 183 }
 184
 185 /**
 186  * list_add_tail - add an entry at the end of a linked list.
 187  * @h: the list_head to add the node to
 188  * @n: the list_node to add to the list.
 189  *
 190  * The list_node does not need to be initialized; it will be overwritten.
 191  * Example:
 192  *      list_add_tail(&parent->children, &child->list);
 193  *      parent->num_children++;
 194  */
 195 #define list_add_tail(h, n) list_add_tail_(h, n, LIST_LOC)
 196 static inline void list_add_tail_(struct list_head *h,
 197                                   struct list_node *n,
 198                                   const char *abortstr)
 199 {
 200         n->next = &h->n;
 201         n->prev = h->n.prev;
 202         h->n.prev->next = n;
 203         h->n.prev = n;
 204         (void)list_debug(h, abortstr);
 205 }
 206
 207 /**
 208  * list_empty - is a list empty?
 209  * @h: the list_head
 210  *
 211  * If the list is empty, returns true.
 212  *
 213  * Example:
 214  *      assert(list_empty(&parent->children) == (parent->num_children == 0));
 215  */
 216 #define list_empty(h) list_empty_(h, LIST_LOC)
 217 static inline bool list_empty_(const struct list_head *h, const char* abortstr)
 218 {
 219         (void)list_debug(h, abortstr);
 220         return h->n.next == &h->n;
 221 }
 222
 223 /**
 224  * list_empty_nodebug - is a list empty (and don't perform debug checks)?
 225  * @h: the list_head
 226  *
 227  * If the list is empty, returns true.
 228  * This differs from list_empty() in that if CCAN_LIST_DEBUG is set it
 229  * will NOT perform debug checks. Only use this function if you REALLY
 230  * know what you're doing.
 231  *
 232  * Example:
 233  *      assert(list_empty_nodebug(&parent->children) == (parent->num_children == 0));
 234  */
 235 #ifndef CCAN_LIST_DEBUG
 236 #define list_empty_nodebug(h) list_empty(h)
 237 #else
 238 static inline bool list_empty_nodebug(const struct list_head *h)
 239 {
 240         return h->n.next == &h->n;
 241 }
 242 #endif
 243
 244 /**
 245  * list_del - delete an entry from an (unknown) linked list.
 246  * @n: the list_node to delete from the list.
 247  *
 248  * Note that this leaves @n in an undefined state; it can be added to
 249  * another list, but not deleted again.
 250  *
 251  * See also:
 252  *      list_del_from(), list_del_init()
 253  *
 254  * Example:
 255  *      list_del(&child->list);
 256  *      parent->num_children--;
 257  */
 258 #define list_del(n) list_del_(n, LIST_LOC)
 259 static inline void list_del_(struct list_node *n, const char* abortstr)
 260 {
 261         (void)list_debug_node(n, abortstr);
 262         n->next->prev = n->prev;
 263         n->prev->next = n->next;
 264 #ifdef CCAN_LIST_DEBUG
 265         /* Catch use-after-del. */
 266         n->next = n->prev = NULL;
 267 #endif
 268 }
 269
 270 /**
 271  * list_del_init - delete a node, and reset it so it can be deleted again.
 272  * @n: the list_node to be deleted.
 273  *
 274  * list_del(@n) or list_del_init() again after this will be safe,
 275  * which can be useful in some cases.
 276  *
 277  * See also:
 278  *      list_del_from(), list_del()
 279  *
 280  * Example:
 281  *      list_del_init(&child->list);
 282  *      parent->num_children--;
 283  */
 284 #define list_del_init(n) list_del_init_(n, LIST_LOC)
 285 static inline void list_del_init_(struct list_node *n, const char *abortstr)
 286 {
 287         list_del_(n, abortstr);
 288         list_node_init(n);
 289 }
 290
 291 /**
 292  * list_del_from - delete an entry from a known linked list.
 293  * @h: the list_head the node is in.
 294  * @n: the list_node to delete from the list.
 295  *
 296  * This explicitly indicates which list a node is expected to be in,
 297  * which is better documentation and can catch more bugs.
 298  *
 299  * See also: list_del()
 300  *
 301  * Example:
 302  *      list_del_from(&parent->children, &child->list);
 303  *      parent->num_children--;
 304  */
 305 static inline void list_del_from(struct list_head *h, struct list_node *n)
 306 {
 307 #ifdef CCAN_LIST_DEBUG
 308         {
 309                 /* Thorough check: make sure it was in list! */
 310                 struct list_node *i;
 311                 for (i = h->n.next; i != n; i = i->next)
 312                         assert(i != &h->n);
 313         }
 314 #endif /* CCAN_LIST_DEBUG */
 315
 316         /* Quick test that catches a surprising number of bugs. */
 317         assert(!list_empty(h));
 318         list_del(n);
 319 }
 320
 321 /**
 322  * list_entry - convert a list_node back into the structure containing it.
 323  * @n: the list_node
 324  * @type: the type of the entry
 325  * @member: the list_node member of the type
 326  *
 327  * Example:
 328  *      // First list entry is children.next; convert back to child.
 329  *      child = list_entry(parent->children.n.next, struct child, list);
 330  *
 331  * See Also:
 332  *      list_top(), list_for_each()
 333  */
 334 #define list_entry(n, type, member) container_of(n, type, member)
 335
 336 /**
 337  * list_top - get the first entry in a list
 338  * @h: the list_head
 339  * @type: the type of the entry
 340  * @member: the list_node member of the type
 341  *
 342  * If the list is empty, returns NULL.
 343  *
 344  * Example:
 345  *      struct child *first;
 346  *      first = list_top(&parent->children, struct child, list);
 347  *      if (!first)
 348  *              printf("Empty list!\n");
 349  */
 350 #define list_top(h, type, member)                                       \
 351         ((type *)list_top_((h), list_off_(type, member)))
 352
 353 static inline const void *list_top_(const struct list_head *h, size_t off)
 354 {
 355         if (list_empty(h))
 356                 return NULL;
 357         return (const char *)h->n.next - off;
 358 }
 359
 360 /**
 361  * list_pop - remove the first entry in a list
 362  * @h: the list_head
 363  * @type: the type of the entry
 364  * @member: the list_node member of the type
 365  *
 366  * If the list is empty, returns NULL.
 367  *
 368  * Example:
 369  *      struct child *one;
 370  *      one = list_pop(&parent->children, struct child, list);
 371  *      if (!one)
 372  *              printf("Empty list!\n");
 373  */
 374 #define list_pop(h, type, member)                                       \
 375         ((type *)list_pop_((h), list_off_(type, member)))
 376
 377 static inline const void *list_pop_(const struct list_head *h, size_t off)
 378 {
 379         struct list_node *n;
 380
 381         if (list_empty(h))
 382                 return NULL;
 383         n = h->n.next;
 384         list_del(n);
 385         return (const char *)n - off;
 386 }
 387
 388 /**
 389  * list_tail - get the last entry in a list
 390  * @h: the list_head
 391  * @type: the type of the entry
 392  * @member: the list_node member of the type
 393  *
 394  * If the list is empty, returns NULL.
 395  *
 396  * Example:
 397  *      struct child *last;
 398  *      last = list_tail(&parent->children, struct child, list);
 399  *      if (!last)
 400  *              printf("Empty list!\n");
 401  */
 402 #define list_tail(h, type, member) \
 403         ((type *)list_tail_((h), list_off_(type, member)))
 404
 405 static inline const void *list_tail_(const struct list_head *h, size_t off)
 406 {
 407         if (list_empty(h))
 408                 return NULL;
 409         return (const char *)h->n.prev - off;
 410 }
 411
 412 /**
 413  * list_for_each - iterate through a list.
 414  * @h: the list_head (warning: evaluated multiple times!)
 415  * @i: the structure containing the list_node
 416  * @member: the list_node member of the structure
 417  *
 418  * This is a convenient wrapper to iterate @i over the entire list.  It's
 419  * a for loop, so you can break and continue as normal.
 420  *
 421  * Example:
 422  *      list_for_each(&parent->children, child, list)
 423  *              printf("Name: %s\n", child->name);
 424  */
 425 #define list_for_each(h, i, member)                                     \
 426         list_for_each_off(h, i, list_off_var_(i, member))
 427
 428 /**
 429  * list_for_each_rev - iterate through a list backwards.
 430  * @h: the list_head
 431  * @i: the structure containing the list_node
 432  * @member: the list_node member of the structure
 433  *
 434  * This is a convenient wrapper to iterate @i over the entire list.  It's
 435  * a for loop, so you can break and continue as normal.
 436  *
 437  * Example:
 438  *      list_for_each_rev(&parent->children, child, list)
 439  *              printf("Name: %s\n", child->name);
 440  */
 441 #define list_for_each_rev(h, i, member)                                 \
 442         for (i = container_of_var(list_debug(h, LIST_LOC)->n.prev, i, member); \
 443              &i->member != &(h)->n;                                     \
 444              i = container_of_var(i->member.prev, i, member))
 445
 446 /**
 447  * list_for_each_safe - iterate through a list, maybe during deletion
 448  * @h: the list_head
 449  * @i: the structure containing the list_node
 450  * @nxt: the structure containing the list_node
 451  * @member: the list_node member of the structure
 452  *
 453  * This is a convenient wrapper to iterate @i over the entire list.  It's
 454  * a for loop, so you can break and continue as normal.  The extra variable
 455  * @nxt is used to hold the next element, so you can delete @i from the list.
 456  *
 457  * Example:
 458  *      struct child *next;
 459  *      list_for_each_safe(&parent->children, child, next, list) {
 460  *              list_del(&child->list);
 461  *              parent->num_children--;
 462  *      }
 463  */
 464 #define list_for_each_safe(h, i, nxt, member)                           \
 465         list_for_each_safe_off(h, i, nxt, list_off_var_(i, member))
 466
 467 /**
 468  * list_next - get the next entry in a list
 469  * @h: the list_head
 470  * @i: a pointer to an entry in the list.
 471  * @member: the list_node member of the structure
 472  *
 473  * If @i was the last entry in the list, returns NULL.
 474  *
 475  * Example:
 476  *      struct child *second;
 477  *      second = list_next(&parent->children, first, list);
 478  *      if (!second)
 479  *              printf("No second child!\n");
 480  */
 481 #define list_next(h, i, member)                                         \
 482         ((list_typeof(i))list_entry_or_null(list_debug(h,               \
 483                                             __FILE__ ":" stringify(__LINE__)), \
 484                                             (i)->member.next,           \
 485                                             list_off_var_((i), member)))
 486
 487 /**
 488  * list_prev - get the previous entry in a list
 489  * @h: the list_head
 490  * @i: a pointer to an entry in the list.
 491  * @member: the list_node member of the structure
 492  *
 493  * If @i was the first entry in the list, returns NULL.
 494  *
 495  * Example:
 496  *      first = list_prev(&parent->children, second, list);
 497  *      if (!first)
 498  *              printf("Can't go back to first child?!\n");
 499  */
 500 #define list_prev(h, i, member)                                         \
 501         ((list_typeof(i))list_entry_or_null(list_debug(h,               \
 502                                             __FILE__ ":" stringify(__LINE__)), \
 503                                             (i)->member.prev,           \
 504                                             list_off_var_((i), member)))
 505
 506 /**
 507  * list_append_list - empty one list onto the end of another.
 508  * @to: the list to append into
 509  * @from: the list to empty.
 510  *
 511  * This takes the entire contents of @from and moves it to the end of
 512  * @to.  After this @from will be empty.
 513  *
 514  * Example:
 515  *      struct list_head adopter;
 516  *
 517  *      list_append_list(&adopter, &parent->children);
 518  *      assert(list_empty(&parent->children));
 519  *      parent->num_children = 0;
 520  */
 521 #define list_append_list(t, f) list_append_list_(t, f,                  \
 522                                    __FILE__ ":" stringify(__LINE__))
 523 static inline void list_append_list_(struct list_head *to,
 524                                      struct list_head *from,
 525                                      const char *abortstr)
 526 {
 527         struct list_node *from_tail = list_debug(from, abortstr)->n.prev;
 528         struct list_node *to_tail = list_debug(to, abortstr)->n.prev;
 529
 530         /* Sew in head and entire list. */
 531         to->n.prev = from_tail;
 532         from_tail->next = &to->n;
 533         to_tail->next = &from->n;
 534         from->n.prev = to_tail;
 535
 536         /* Now remove head. */
 537         list_del(&from->n);
 538         list_head_init(from);
 539 }
 540
 541 /**
 542  * list_prepend_list - empty one list into the start of another.
 543  * @to: the list to prepend into
 544  * @from: the list to empty.
 545  *
 546  * This takes the entire contents of @from and moves it to the start
 547  * of @to.  After this @from will be empty.
 548  *
 549  * Example:
 550  *      list_prepend_list(&adopter, &parent->children);
 551  *      assert(list_empty(&parent->children));
 552  *      parent->num_children = 0;
 553  */
 554 #define list_prepend_list(t, f) list_prepend_list_(t, f, LIST_LOC)
 555 static inline void list_prepend_list_(struct list_head *to,
 556                                       struct list_head *from,
 557                                       const char *abortstr)
 558 {
 559         struct list_node *from_tail = list_debug(from, abortstr)->n.prev;
 560         struct list_node *to_head = list_debug(to, abortstr)->n.next;
 561
 562         /* Sew in head and entire list. */
 563         to->n.next = &from->n;
 564         from->n.prev = &to->n;
 565         to_head->prev = from_tail;
 566         from_tail->next = to_head;
 567
 568         /* Now remove head. */
 569         list_del(&from->n);
 570         list_head_init(from);
 571 }
 572
 573 /**
 574  * list_for_each_off - iterate through a list of memory regions.
 575  * @h: the list_head
 576  * @i: the pointer to a memory region wich contains list node data.
 577  * @off: offset(relative to @i) at which list node data resides.
 578  *
 579  * This is a low-level wrapper to iterate @i over the entire list, used to
 580  * implement all oher, more high-level, for-each constructs. It's a for loop,
 581  * so you can break and continue as normal.
 582  *
 583  * WARNING! Being the low-level macro that it is, this wrapper doesn't know
 584  * nor care about the type of @i. The only assumtion made is that @i points
 585  * to a chunk of memory that at some @offset, relative to @i, contains a
 586  * properly filled `struct node_list' which in turn contains pointers to
 587  * memory chunks and it's turtles all the way down. Whith all that in mind
 588  * remember that given the wrong pointer/offset couple this macro will
 589  * happilly churn all you memory untill SEGFAULT stops it, in other words
 590  * caveat emptor.
 591  *
 592  * It is worth mentioning that one of legitimate use-cases for that wrapper
 593  * is operation on opaque types with known offset for `struct list_node'
 594  * member(preferably 0), because it allows you not to disclose the type of
 595  * @i.
 596  *
 597  * Example:
 598  *      list_for_each_off(&parent->children, child,
 599  *                              offsetof(struct child, list))
 600  *              printf("Name: %s\n", child->name);
 601  */
 602 #define list_for_each_off(h, i, off)                                    \
 603         for (i = list_node_to_off_(list_debug(h, LIST_LOC)->n.next,     \
 604                                    (off));                              \
 605        list_node_from_off_((void *)i, (off)) != &(h)->n;                \
 606        i = list_node_to_off_(list_node_from_off_((void *)i, (off))->next, \
 607                              (off)))
 608
 609 /**
 610  * list_for_each_safe_off - iterate through a list of memory regions, maybe
 611  * during deletion
 612  * @h: the list_head
 613  * @i: the pointer to a memory region wich contains list node data.
 614  * @nxt: the structure containing the list_node
 615  * @off: offset(relative to @i) at which list node data resides.
 616  *
 617  * For details see `list_for_each_off' and `list_for_each_safe'
 618  * descriptions.
 619  *
 620  * Example:
 621  *      list_for_each_safe_off(&parent->children, child,
 622  *              next, offsetof(struct child, list))
 623  *              printf("Name: %s\n", child->name);
 624  */
 625 #define list_for_each_safe_off(h, i, nxt, off)                          \
 626         for (i = list_node_to_off_(list_debug(h, LIST_LOC)->n.next,     \
 627                                    (off)),                              \
 628          nxt = list_node_to_off_(list_node_from_off_(i, (off))->next,   \
 629                                  (off));                                \
 630        list_node_from_off_(i, (off)) != &(h)->n;                        \
 631        i = nxt,                                                         \
 632          nxt = list_node_to_off_(list_node_from_off_(i, (off))->next,   \
 633                                  (off)))
 634
 635
 636 /* Other -off variants. */
 637 #define list_entry_off(n, type, off)            \
 638         ((type *)list_node_from_off_((n), (off)))
 639
 640 #define list_head_off(h, type, off)             \
 641         ((type *)list_head_off((h), (off)))
 642
 643 #define list_tail_off(h, type, off)             \
 644         ((type *)list_tail_((h), (off)))
 645
 646 #define list_add_off(h, n, off)                 \
 647         list_add((h), list_node_from_off_((n), (off)))
 648
 649 #define list_del_off(n, off)                    \
 650         list_del(list_node_from_off_((n), (off)))
 651
 652 #define list_del_from_off(h, n, off)                    \
 653         list_del_from(h, list_node_from_off_((n), (off)))
 654
 655 /* Offset helper functions so we only single-evaluate. */
 656 static inline void *list_node_to_off_(struct list_node *node, size_t off)
 657 {
 658         return (void *)((char *)node - off);
 659 }
 660 static inline struct list_node *list_node_from_off_(void *ptr, size_t off)
 661 {
 662         return (struct list_node *)((char *)ptr + off);
 663 }
 664
 665 /* Get the offset of the member, but make sure it's a list_node. */
 666 #define list_off_(type, member)                                 \
 667         (container_off(type, member) +                          \
 668          check_type(((type *)0)->member, struct list_node))
 669
 670 #define list_off_var_(var, member)                      \
 671         (container_off_var(var, member) +               \
 672          check_type(var->member, struct list_node))
 673
 674 #if HAVE_TYPEOF
 675 #define list_typeof(var) typeof(var)
 676 #else
 677 #define list_typeof(var) void *
 678 #endif
 679
 680 /* Returns member, or NULL if at end of list. */
 681 static inline void *list_entry_or_null(const struct list_head *h,
 682                                        const struct list_node *n,
 683                                        size_t off)
 684 {
 685         if (n == &h->n)
 686                 return NULL;
 687         return (char *)n - off;
 688 }
 689 #endif /* CCAN_LIST_H */