lib/list.h

   1 /*
   2  * Copyright (c) 2008, 2009, 2010, 2011, 2013 Nicira, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at:
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 #ifndef LIST_H
  17 #define LIST_H 1
  18
  19 /* Doubly linked list. */
  20
  21 #include <stdbool.h>
  22 #include <stddef.h>
  23 #include "util.h"
  24
  25 /* Doubly linked list head or element. */
  26 struct list {
  27     struct list *prev;     /* Previous list element. */
  28     struct list *next;     /* Next list element. */
  29 };
  30
  31 #define LIST_INITIALIZER(LIST) { LIST, LIST }
  32
  33 static inline void list_init(struct list *);
  34 static inline void list_poison(struct list *);
  35
  36 /* List insertion. */
  37 static inline void list_insert(struct list *, struct list *);
  38 static inline void list_splice(struct list *before, struct list *first,
  39                                struct list *last);
  40 static inline void list_push_front(struct list *, struct list *);
  41 static inline void list_push_back(struct list *, struct list *);
  42 static inline void list_replace(struct list *, const struct list *);
  43 static inline void list_moved(struct list *);
  44 static inline void list_move(struct list *dst, struct list *src);
  45
  46 /* List removal. */
  47 static inline struct list *list_remove(struct list *);
  48 static inline struct list *list_pop_front(struct list *);
  49 static inline struct list *list_pop_back(struct list *);
  50
  51 /* List elements. */
  52 static inline struct list *list_front(const struct list *);
  53 static inline struct list *list_back(const struct list *);
  54
  55 /* List properties. */
  56 static inline size_t list_size(const struct list *);
  57 static inline bool list_is_empty(const struct list *);
  58 static inline bool list_is_singleton(const struct list *);
  59 static inline bool list_is_short(const struct list *);
  60
  61 #define LIST_FOR_EACH(ITER, MEMBER, LIST)                               \
  62     for (INIT_CONTAINER(ITER, (LIST)->next, MEMBER);                    \
  63          &(ITER)->MEMBER != (LIST);                                     \
  64          ASSIGN_CONTAINER(ITER, (ITER)->MEMBER.next, MEMBER))
  65 #define LIST_FOR_EACH_CONTINUE(ITER, MEMBER, LIST)                      \
  66     for (INIT_CONTAINER(ITER, (ITER)->MEMBER.next, MEMBER);             \
  67          &(ITER)->MEMBER != (LIST);                                     \
  68          ASSIGN_CONTAINER(ITER, (ITER)->MEMBER.next, MEMBER))
  69 #define LIST_FOR_EACH_REVERSE(ITER, MEMBER, LIST)                       \
  70     for (INIT_CONTAINER(ITER, (LIST)->prev, MEMBER);                    \
  71          &(ITER)->MEMBER != (LIST);                                     \
  72          ASSIGN_CONTAINER(ITER, (ITER)->MEMBER.prev, MEMBER))
  73 #define LIST_FOR_EACH_REVERSE_CONTINUE(ITER, MEMBER, LIST)              \
  74     for (ASSIGN_CONTAINER(ITER, (ITER)->MEMBER.prev, MEMBER);           \
  75          &(ITER)->MEMBER != (LIST);                                     \
  76          ASSIGN_CONTAINER(ITER, (ITER)->MEMBER.prev, MEMBER))
  77 #define LIST_FOR_EACH_SAFE(ITER, NEXT, MEMBER, LIST)               \
  78     for (INIT_CONTAINER(ITER, (LIST)->next, MEMBER);               \
  79          (&(ITER)->MEMBER != (LIST)                                \
  80           ? INIT_CONTAINER(NEXT, (ITER)->MEMBER.next, MEMBER), 1   \
  81           : 0);                                                    \
  82          (ITER) = (NEXT))
  83 \f
  84 /* Inline implementations. */
  85
  86 /* Initializes 'list' as an empty list. */
  87 static inline void
  88 list_init(struct list *list)
  89 {
  90     list->next = list->prev = list;
  91 }
  92
  93 /* Initializes 'list' with pointers that will (probably) cause segfaults if
  94  * dereferenced and, better yet, show up clearly in a debugger. */
  95 static inline void
  96 list_poison(struct list *list)
  97 {
  98     memset(list, 0xcc, sizeof *list);
  99 }
 100
 101 /* Inserts 'elem' just before 'before'. */
 102 static inline void
 103 list_insert(struct list *before, struct list *elem)
 104 {
 105     elem->prev = before->prev;
 106     elem->next = before;
 107     before->prev->next = elem;
 108     before->prev = elem;
 109 }
 110
 111 /* Removes elements 'first' though 'last' (exclusive) from their current list,
 112    then inserts them just before 'before'. */
 113 static inline void
 114 list_splice(struct list *before, struct list *first, struct list *last)
 115 {
 116     if (first == last) {
 117         return;
 118     }
 119     last = last->prev;
 120
 121     /* Cleanly remove 'first'...'last' from its current list. */
 122     first->prev->next = last->next;
 123     last->next->prev = first->prev;
 124
 125     /* Splice 'first'...'last' into new list. */
 126     first->prev = before->prev;
 127     last->next = before;
 128     before->prev->next = first;
 129     before->prev = last;
 130 }
 131
 132 /* Inserts 'elem' at the beginning of 'list', so that it becomes the front in
 133    'list'. */
 134 static inline void
 135 list_push_front(struct list *list, struct list *elem)
 136 {
 137     list_insert(list->next, elem);
 138 }
 139
 140 /* Inserts 'elem' at the end of 'list', so that it becomes the back in
 141  * 'list'. */
 142 static inline void
 143 list_push_back(struct list *list, struct list *elem)
 144 {
 145     list_insert(list, elem);
 146 }
 147
 148 /* Puts 'elem' in the position currently occupied by 'position'.
 149  * Afterward, 'position' is not part of a list. */
 150 static inline void
 151 list_replace(struct list *element, const struct list *position)
 152 {
 153     element->next = position->next;
 154     element->next->prev = element;
 155     element->prev = position->prev;
 156     element->prev->next = element;
 157 }
 158
 159 /* Adjusts pointers around 'list' to compensate for 'list' having been moved
 160  * around in memory (e.g. as a consequence of realloc()).
 161  *
 162  * This always works if 'list' is a member of a list, or if 'list' is the head
 163  * of a non-empty list.  It fails badly, however, if 'list' is the head of an
 164  * empty list; just use list_init() in that case. */
 165 static inline void
 166 list_moved(struct list *list)
 167 {
 168     list->prev->next = list->next->prev = list;
 169 }
 170
 171 /* Initializes 'dst' with the contents of 'src', compensating for moving it
 172  * around in memory.  The effect is that, if 'src' was the head of a list, now
 173  * 'dst' is the head of a list containing the same elements. */
 174 static inline void
 175 list_move(struct list *dst, struct list *src)
 176 {
 177     if (!list_is_empty(src)) {
 178         *dst = *src;
 179         list_moved(dst);
 180     } else {
 181         list_init(dst);
 182     }
 183 }
 184
 185 /* Removes 'elem' from its list and returns the element that followed it.
 186    Undefined behavior if 'elem' is not in a list. */
 187 static inline struct list *
 188 list_remove(struct list *elem)
 189 {
 190     elem->prev->next = elem->next;
 191     elem->next->prev = elem->prev;
 192     return elem->next;
 193 }
 194
 195 /* Removes the front element from 'list' and returns it.  Undefined behavior if
 196    'list' is empty before removal. */
 197 static inline struct list *
 198 list_pop_front(struct list *list)
 199 {
 200     struct list *front = list->next;
 201
 202     list_remove(front);
 203     return front;
 204 }
 205
 206 /* Removes the back element from 'list' and returns it.
 207    Undefined behavior if 'list' is empty before removal. */
 208 static inline struct list *
 209 list_pop_back(struct list *list)
 210 {
 211     struct list *back = list->prev;
 212
 213     list_remove(back);
 214     return back;
 215 }
 216
 217 /* Returns the front element in 'list_'.
 218    Undefined behavior if 'list_' is empty. */
 219 static inline struct list *
 220 list_front(const struct list *list_)
 221 {
 222     struct list *list = CONST_CAST(struct list *, list_);
 223
 224     ovs_assert(!list_is_empty(list));
 225
 226     return list->next;
 227 }
 228
 229 /* Returns the back element in 'list_'.
 230    Undefined behavior if 'list_' is empty. */
 231 static inline struct list *
 232 list_back(const struct list *list_)
 233 {
 234     struct list *list = CONST_CAST(struct list *, list_);
 235
 236     ovs_assert(!list_is_empty(list));
 237
 238     return list->prev;
 239 }
 240
 241 /* Returns the number of elements in 'list'.
 242    Runs in O(n) in the number of elements. */
 243 static inline size_t
 244 list_size(const struct list *list)
 245 {
 246     const struct list *e;
 247     size_t cnt = 0;
 248
 249     for (e = list->next; e != list; e = e->next) {
 250         cnt++;
 251     }
 252     return cnt;
 253 }
 254
 255 /* Returns true if 'list' is empty, false otherwise. */
 256 static inline bool
 257 list_is_empty(const struct list *list)
 258 {
 259     return list->next == list;
 260 }
 261
 262 /* Returns true if 'list' has exactly 1 element, false otherwise. */
 263 static inline bool
 264 list_is_singleton(const struct list *list)
 265 {
 266     return list_is_short(list) && !list_is_empty(list);
 267 }
 268
 269 /* Returns true if 'list' has 0 or 1 elements, false otherwise. */
 270 static inline bool
 271 list_is_short(const struct list *list)
 272 {
 273     return list->next == list->prev;
 274 }
 275
 276 #endif /* list.h */