include/openvswitch/list.h

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