2 * Copyright (c) 2008, 2009, 2010, 2011, 2013, 2015, 2016 Nicira, Inc.
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:
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
16 #ifndef OPENVSWITCH_LIST_H
17 #define OPENVSWITCH_LIST_H 1
22 #include <openvswitch/types.h>
23 #include <openvswitch/util.h>
25 /* Doubly linked list head or element. */
27 struct ovs_list *prev; /* Previous list element. */
28 struct ovs_list *next; /* Next list element. */
31 #define OVS_LIST_INITIALIZER(LIST) { LIST, LIST }
33 /* "struct ovs_list" with pointers that will (probably) cause segfaults if
34 * dereferenced and, better yet, show up clearly in a debugger.
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) };
43 static inline void ovs_list_init(struct ovs_list *);
44 static inline void ovs_list_poison(struct ovs_list *);
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);
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 *);
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 *);
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 *);
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 \
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 \
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))
103 /* Inline implementations. */
105 /* Initializes 'list' as an empty list. */
107 ovs_list_init(struct ovs_list *list)
109 list->next = list->prev = list;
112 /* Initializes 'list' with pointers that will (probably) cause segfaults if
113 * dereferenced and, better yet, show up clearly in a debugger. */
115 ovs_list_poison(struct ovs_list *list)
117 *list = OVS_LIST_POISON;
120 /* Inserts 'elem' just before 'before'. */
122 ovs_list_insert(struct ovs_list *before, struct ovs_list *elem)
124 elem->prev = before->prev;
126 before->prev->next = elem;
130 /* Removes elements 'first' though 'last' (exclusive) from their current list,
131 then inserts them just before 'before'. */
133 ovs_list_splice(struct ovs_list *before, struct ovs_list *first, struct ovs_list *last)
140 /* Cleanly remove 'first'...'last' from its current list. */
141 first->prev->next = last->next;
142 last->next->prev = first->prev;
144 /* Splice 'first'...'last' into new list. */
145 first->prev = before->prev;
147 before->prev->next = first;
151 /* Inserts 'elem' at the beginning of 'list', so that it becomes the front in
154 ovs_list_push_front(struct ovs_list *list, struct ovs_list *elem)
156 ovs_list_insert(list->next, elem);
159 /* Inserts 'elem' at the end of 'list', so that it becomes the back in
162 ovs_list_push_back(struct ovs_list *list, struct ovs_list *elem)
164 ovs_list_insert(list, elem);
167 /* Puts 'elem' in the position currently occupied by 'position'.
168 * Afterward, 'position' is not part of a list. */
170 ovs_list_replace(struct ovs_list *element, const struct ovs_list *position)
172 element->next = position->next;
173 element->next->prev = element;
174 element->prev = position->prev;
175 element->prev->next = element;
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
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.) */
187 ovs_list_moved(struct ovs_list *list, const struct ovs_list *orig)
189 if (list->next == orig) {
192 list->prev->next = list->next->prev = list;
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. */
200 ovs_list_move(struct ovs_list *dst, struct ovs_list *src)
203 ovs_list_moved(dst, src);
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)
211 elem->prev->next = elem->next;
212 elem->next->prev = elem->prev;
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)
221 struct ovs_list *front = list->next;
223 ovs_list_remove(front);
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)
232 struct ovs_list *back = list->prev;
234 ovs_list_remove(back);
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_)
243 struct ovs_list *list = CONST_CAST(struct ovs_list *, list_);
245 ovs_assert(!ovs_list_is_empty(list));
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_)
255 struct ovs_list *list = CONST_CAST(struct ovs_list *, list_);
257 ovs_assert(!ovs_list_is_empty(list));
262 /* Returns the number of elements in 'list'.
263 Runs in O(n) in the number of elements. */
265 ovs_list_size(const struct ovs_list *list)
267 const struct ovs_list *e;
270 for (e = list->next; e != list; e = e->next) {
276 /* Returns true if 'list' is empty, false otherwise. */
278 ovs_list_is_empty(const struct ovs_list *list)
280 return list->next == list;
283 /* Returns true if 'list' has exactly 1 element, false otherwise. */
285 ovs_list_is_singleton(const struct ovs_list *list)
287 return ovs_list_is_short(list) && !ovs_list_is_empty(list);
290 /* Returns true if 'list' has 0 or 1 elements, false otherwise. */
292 ovs_list_is_short(const struct ovs_list *list)
294 return list->next == list->prev;
297 /* Transplant a list into another, and resets the origin list */
299 ovs_list_push_back_all(struct ovs_list *dst, struct ovs_list *src)
301 ovs_list_splice(dst, src->next, src);