lib/list.h

   1 /*
   2  * Copyright (c) 2008, 2009, 2010, 2011, 2013, 2015 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 #include "openvswitch/list.h"
  25
  26 /* "struct ovs_list" with pointers that will (probably) cause segfaults if
  27  * dereferenced and, better yet, show up clearly in a debugger. */
  28 #define OVS_LIST_POISON \
  29 (struct ovs_list) { (struct ovs_list *) (uintptr_t) 0xccccccccccccccccULL, \
  30                     (struct ovs_list *) (uintptr_t) 0xccccccccccccccccULL }
  31
  32 static inline void list_init(struct ovs_list *);
  33 static inline void list_poison(struct ovs_list *);
  34
  35 /* List insertion. */
  36 static inline void list_insert(struct ovs_list *, struct ovs_list *);
  37 static inline void list_splice(struct ovs_list *before, struct ovs_list *first,
  38                                struct ovs_list *last);
  39 static inline void list_push_front(struct ovs_list *, struct ovs_list *);
  40 static inline void list_push_back(struct ovs_list *, struct ovs_list *);
  41 static inline void list_replace(struct ovs_list *, const struct ovs_list *);
  42 static inline void list_moved(struct ovs_list *, const struct ovs_list *orig);
  43 static inline void list_move(struct ovs_list *dst, struct ovs_list *src);
  44
  45 /* List removal. */
  46 static inline struct ovs_list *list_remove(struct ovs_list *);
  47 static inline struct ovs_list *list_pop_front(struct ovs_list *);
  48 static inline struct ovs_list *list_pop_back(struct ovs_list *);
  49
  50 /* List elements. */
  51 static inline struct ovs_list *list_front(const struct ovs_list *);
  52 static inline struct ovs_list *list_back(const struct ovs_list *);
  53
  54 /* List properties. */
  55 static inline size_t list_size(const struct ovs_list *);
  56 static inline bool list_is_empty(const struct ovs_list *);
  57 static inline bool list_is_singleton(const struct ovs_list *);
  58 static inline bool list_is_short(const struct ovs_list *);
  59
  60 #define LIST_FOR_EACH(ITER, MEMBER, LIST)                               \
  61     for (INIT_CONTAINER(ITER, (LIST)->next, MEMBER);                    \
  62          &(ITER)->MEMBER != (LIST);                                     \
  63          ASSIGN_CONTAINER(ITER, (ITER)->MEMBER.next, MEMBER))
  64 #define LIST_FOR_EACH_CONTINUE(ITER, MEMBER, LIST)                      \
  65     for (ASSIGN_CONTAINER(ITER, (ITER)->MEMBER.next, MEMBER);             \
  66          &(ITER)->MEMBER != (LIST);                                     \
  67          ASSIGN_CONTAINER(ITER, (ITER)->MEMBER.next, MEMBER))
  68 #define LIST_FOR_EACH_REVERSE(ITER, MEMBER, LIST)                       \
  69     for (INIT_CONTAINER(ITER, (LIST)->prev, MEMBER);                    \
  70          &(ITER)->MEMBER != (LIST);                                     \
  71          ASSIGN_CONTAINER(ITER, (ITER)->MEMBER.prev, MEMBER))
  72 #define LIST_FOR_EACH_REVERSE_CONTINUE(ITER, MEMBER, LIST)              \
  73     for (ASSIGN_CONTAINER(ITER, (ITER)->MEMBER.prev, MEMBER);           \
  74          &(ITER)->MEMBER != (LIST);                                     \
  75          ASSIGN_CONTAINER(ITER, (ITER)->MEMBER.prev, MEMBER))
  76 #define LIST_FOR_EACH_SAFE(ITER, NEXT, MEMBER, LIST)               \
  77     for (INIT_CONTAINER(ITER, (LIST)->next, MEMBER);               \
  78          (&(ITER)->MEMBER != (LIST)                                \
  79           ? INIT_CONTAINER(NEXT, (ITER)->MEMBER.next, MEMBER), 1   \
  80           : 0);                                                    \
  81          (ITER) = (NEXT))
  82 #define LIST_FOR_EACH_POP(ITER, MEMBER, LIST)                      \
  83     while (!list_is_empty(LIST)                                    \
  84            && (INIT_CONTAINER(ITER, list_pop_front(LIST), MEMBER), 1))
  85 \f
  86 /* Inline implementations. */
  87
  88 /* Initializes 'list' as an empty list. */
  89 static inline void
  90 list_init(struct ovs_list *list)
  91 {
  92     list->next = list->prev = list;
  93 }
  94
  95 /* Initializes 'list' with pointers that will (probably) cause segfaults if
  96  * dereferenced and, better yet, show up clearly in a debugger. */
  97 static inline void
  98 list_poison(struct ovs_list *list)
  99 {
 100     *list = OVS_LIST_POISON;
 101 }
 102
 103 /* Inserts 'elem' just before 'before'. */
 104 static inline void
 105 list_insert(struct ovs_list *before, struct ovs_list *elem)
 106 {
 107     elem->prev = before->prev;
 108     elem->next = before;
 109     before->prev->next = elem;
 110     before->prev = elem;
 111 }
 112
 113 /* Removes elements 'first' though 'last' (exclusive) from their current list,
 114    then inserts them just before 'before'. */
 115 static inline void
 116 list_splice(struct ovs_list *before, struct ovs_list *first, struct ovs_list *last)
 117 {
 118     if (first == last) {
 119         return;
 120     }
 121     last = last->prev;
 122
 123     /* Cleanly remove 'first'...'last' from its current list. */
 124     first->prev->next = last->next;
 125     last->next->prev = first->prev;
 126
 127     /* Splice 'first'...'last' into new list. */
 128     first->prev = before->prev;
 129     last->next = before;
 130     before->prev->next = first;
 131     before->prev = last;
 132 }
 133
 134 /* Inserts 'elem' at the beginning of 'list', so that it becomes the front in
 135    'list'. */
 136 static inline void
 137 list_push_front(struct ovs_list *list, struct ovs_list *elem)
 138 {
 139     list_insert(list->next, elem);
 140 }
 141
 142 /* Inserts 'elem' at the end of 'list', so that it becomes the back in
 143  * 'list'. */
 144 static inline void
 145 list_push_back(struct ovs_list *list, struct ovs_list *elem)
 146 {
 147     list_insert(list, elem);
 148 }
 149
 150 /* Puts 'elem' in the position currently occupied by 'position'.
 151  * Afterward, 'position' is not part of a list. */
 152 static inline void
 153 list_replace(struct ovs_list *element, const struct ovs_list *position)
 154 {
 155     element->next = position->next;
 156     element->next->prev = element;
 157     element->prev = position->prev;
 158     element->prev->next = element;
 159 }
 160
 161 /* Adjusts pointers around 'list' to compensate for 'list' having been moved
 162  * around in memory (e.g. as a consequence of realloc()), with original
 163  * location 'orig'.
 164  *
 165  * ('orig' likely points to freed memory, but this function does not
 166  * dereference 'orig', it only compares it to 'list'.  In a very pedantic
 167  * language lawyer sense, this still yields undefined behavior, but it works
 168  * with actual compilers.) */
 169 static inline void
 170 list_moved(struct ovs_list *list, const struct ovs_list *orig)
 171 {
 172     if (list->next == orig) {
 173         list_init(list);
 174     } else {
 175         list->prev->next = list->next->prev = list;
 176     }
 177 }
 178
 179 /* Initializes 'dst' with the contents of 'src', compensating for moving it
 180  * around in memory.  The effect is that, if 'src' was the head of a list, now
 181  * 'dst' is the head of a list containing the same elements. */
 182 static inline void
 183 list_move(struct ovs_list *dst, struct ovs_list *src)
 184 {
 185     *dst = *src;
 186     list_moved(dst, src);
 187 }
 188
 189 /* Removes 'elem' from its list and returns the element that followed it.
 190    Undefined behavior if 'elem' is not in a list. */
 191 static inline struct ovs_list *
 192 list_remove(struct ovs_list *elem)
 193 {
 194     elem->prev->next = elem->next;
 195     elem->next->prev = elem->prev;
 196     return elem->next;
 197 }
 198
 199 /* Removes the front element from 'list' and returns it.  Undefined behavior if
 200    'list' is empty before removal. */
 201 static inline struct ovs_list *
 202 list_pop_front(struct ovs_list *list)
 203 {
 204     struct ovs_list *front = list->next;
 205
 206     list_remove(front);
 207     return front;
 208 }
 209
 210 /* Removes the back element from 'list' and returns it.
 211    Undefined behavior if 'list' is empty before removal. */
 212 static inline struct ovs_list *
 213 list_pop_back(struct ovs_list *list)
 214 {
 215     struct ovs_list *back = list->prev;
 216
 217     list_remove(back);
 218     return back;
 219 }
 220
 221 /* Returns the front element in 'list_'.
 222    Undefined behavior if 'list_' is empty. */
 223 static inline struct ovs_list *
 224 list_front(const struct ovs_list *list_)
 225 {
 226     struct ovs_list *list = CONST_CAST(struct ovs_list *, list_);
 227
 228     ovs_assert(!list_is_empty(list));
 229
 230     return list->next;
 231 }
 232
 233 /* Returns the back element in 'list_'.
 234    Undefined behavior if 'list_' is empty. */
 235 static inline struct ovs_list *
 236 list_back(const struct ovs_list *list_)
 237 {
 238     struct ovs_list *list = CONST_CAST(struct ovs_list *, list_);
 239
 240     ovs_assert(!list_is_empty(list));
 241
 242     return list->prev;
 243 }
 244
 245 /* Returns the number of elements in 'list'.
 246    Runs in O(n) in the number of elements. */
 247 static inline size_t
 248 list_size(const struct ovs_list *list)
 249 {
 250     const struct ovs_list *e;
 251     size_t cnt = 0;
 252
 253     for (e = list->next; e != list; e = e->next) {
 254         cnt++;
 255     }
 256     return cnt;
 257 }
 258
 259 /* Returns true if 'list' is empty, false otherwise. */
 260 static inline bool
 261 list_is_empty(const struct ovs_list *list)
 262 {
 263     return list->next == list;
 264 }
 265
 266 /* Returns true if 'list' has exactly 1 element, false otherwise. */
 267 static inline bool
 268 list_is_singleton(const struct ovs_list *list)
 269 {
 270     return list_is_short(list) && !list_is_empty(list);
 271 }
 272
 273 /* Returns true if 'list' has 0 or 1 elements, false otherwise. */
 274 static inline bool
 275 list_is_short(const struct ovs_list *list)
 276 {
 277     return list->next == list->prev;
 278 }
 279
 280 #endif /* list.h */