9  * @defgroup doubly-linked-list_apis Doubly-linked list
12  * @brief Doubly-linked list implementation
14  * Doubly-linked list implementation using inline macros/functions.
15  * This API is not thread safe, and thus if a list is used across threads,
19  * pointers point to the list itself.  Initializing the lists in such a fashion
20  * simplifies the adding and removing of nodes to/from the list.
38 		struct _dnode *head; /* ptr to head of list (sys_dlist_t) */
42 		struct _dnode *tail; /* ptr to tail of list (sys_dlist_t) */
48  * @brief Doubly-linked list structure.
52  * @brief Doubly-linked list node structure.
58  * @brief Provide the primitive to iterate on a list
70  * @param __dn A sys_dnode_t pointer to peek each node of the list
77  * @brief Provide the primitive to iterate on a list, from a node in the list
86  * Like SYS_DLIST_FOR_EACH_NODE(), but __dn already contains a node in the list
93  * @param __dn A sys_dnode_t pointer to peek each node of the list;
103  * @brief Provide the primitive to safely iterate on a list
115  * @param __dn A sys_dnode_t pointer to peek each node of the list
125  * @brief Provide the primitive to resolve the container of a list node
135  * @brief Provide the primitive to peek container of the list head
157  * @brief Provide the primitive to iterate on a list under a container
167  * @param __cn A container struct type pointer to peek each entry of the list
176  * @brief Provide the primitive to safely iterate on a list under a container
186  * @param __cn A container struct type pointer to peek each entry of the list
197  * @brief initialize list to its empty state
199  * @param list the doubly-linked list
202 static inline void sys_dlist_init(sys_dlist_t *list)  in sys_dlist_init()  argument
204 	list->head = (sys_dnode_t *)list;  in sys_dlist_init()
205 	list->tail = (sys_dnode_t *)list;  in sys_dlist_init()
209  * @brief Static initializer for a doubly-linked list
214  * @brief initialize node to its state when not in a list
226  * @brief check if a node is a member of any list
230  * @return true if node is linked into a list, false if it is not
239  * @brief check if a node is the list's head
241  * @param list the doubly-linked list to operate on
247 static inline bool sys_dlist_is_head(sys_dlist_t *list, sys_dnode_t *node)  in sys_dlist_is_head()  argument
249 	return list->head == node;  in sys_dlist_is_head()
253  * @brief check if a node is the list's tail
255  * @param list the doubly-linked list to operate on
261 static inline bool sys_dlist_is_tail(sys_dlist_t *list, sys_dnode_t *node)  in sys_dlist_is_tail()  argument
263 	return list->tail == node;  in sys_dlist_is_tail()
267  * @brief check if the list is empty
269  * @param list the doubly-linked list to operate on
274 static inline bool sys_dlist_is_empty(sys_dlist_t *list)  in sys_dlist_is_empty()  argument
276 	return list->head == list;  in sys_dlist_is_empty()
284  * @param list the doubly-linked list to operate on
289 static inline bool sys_dlist_has_multiple_nodes(sys_dlist_t *list)  in sys_dlist_has_multiple_nodes()  argument
291 	return list->head != list->tail;  in sys_dlist_has_multiple_nodes()
295  * @brief get a reference to the head item in the list
297  * @param list the doubly-linked list to operate on
299  * @return a pointer to the head element, NULL if list is empty
302 static inline sys_dnode_t *sys_dlist_peek_head(sys_dlist_t *list)  in sys_dlist_peek_head()  argument
304 	return sys_dlist_is_empty(list) ? NULL : list->head;  in sys_dlist_peek_head()
308  * @brief get a reference to the head item in the list
310  * The list must be known to be non-empty.
312  * @param list the doubly-linked list to operate on
317 static inline sys_dnode_t *sys_dlist_peek_head_not_empty(sys_dlist_t *list)  in sys_dlist_peek_head_not_empty()  argument
319 	return list->head;  in sys_dlist_peek_head_not_empty()
323  * @brief get a reference to the next item in the list, node is not NULL
327  * @param list the doubly-linked list to operate on
328  * @param node the node from which to get the next element in the list
333 static inline sys_dnode_t *sys_dlist_peek_next_no_check(sys_dlist_t *list,  in sys_dlist_peek_next_no_check()  argument
336 	return (node == list->tail) ? NULL : node->next;  in sys_dlist_peek_next_no_check()
340  * @brief get a reference to the next item in the list
342  * @param list the doubly-linked list to operate on
343  * @param node the node from which to get the next element in the list
346  * or NULL (when node comes from reading the head of an empty list).
349 static inline sys_dnode_t *sys_dlist_peek_next(sys_dlist_t *list,  in sys_dlist_peek_next()  argument
352 	return (node != NULL) ? sys_dlist_peek_next_no_check(list, node) : NULL;  in sys_dlist_peek_next()
356  * @brief get a reference to the previous item in the list, node is not NULL
360  * @param list the doubly-linked list to operate on
361  * @param node the node from which to get the previous element in the list
367 static inline sys_dnode_t *sys_dlist_peek_prev_no_check(sys_dlist_t *list,  in sys_dlist_peek_prev_no_check()  argument
370 	return (node == list->head) ? NULL : node->prev;  in sys_dlist_peek_prev_no_check()
374  * @brief get a reference to the previous item in the list
376  * @param list the doubly-linked list to operate on
377  * @param node the node from which to get the previous element in the list
381  * 	   list).
384 static inline sys_dnode_t *sys_dlist_peek_prev(sys_dlist_t *list,  in sys_dlist_peek_prev()  argument
387 	return (node != NULL) ? sys_dlist_peek_prev_no_check(list, node) : NULL;  in sys_dlist_peek_prev()
391  * @brief get a reference to the tail item in the list
393  * @param list the doubly-linked list to operate on
395  * @return a pointer to the tail element, NULL if list is empty
398 static inline sys_dnode_t *sys_dlist_peek_tail(sys_dlist_t *list)  in sys_dlist_peek_tail()  argument
400 	return sys_dlist_is_empty(list) ? NULL : list->tail;  in sys_dlist_peek_tail()
404  * @brief add node to tail of list
408  * @param list the doubly-linked list to operate on
412 static inline void sys_dlist_append(sys_dlist_t *list, sys_dnode_t *node)  in sys_dlist_append()  argument
414 	sys_dnode_t *const tail = list->tail;  in sys_dlist_append()
416 	node->next = list;  in sys_dlist_append()
420 	list->tail = node;  in sys_dlist_append()
424  * @brief add node to head of list
428  * @param list the doubly-linked list to operate on
432 static inline void sys_dlist_prepend(sys_dlist_t *list, sys_dnode_t *node)  in sys_dlist_prepend()  argument
434 	sys_dnode_t *const head = list->head;  in sys_dlist_prepend()
437 	node->prev = list;  in sys_dlist_prepend()
440 	list->head = node;  in sys_dlist_prepend()
444  * @brief Insert a node into a list
469  * @param list the doubly-linked list to operate on
476 static inline void sys_dlist_insert_at(sys_dlist_t *list, sys_dnode_t *node,  in sys_dlist_insert_at()  argument
479 	if (sys_dlist_is_empty(list)) {  in sys_dlist_insert_at()
480 		sys_dlist_append(list, node);  in sys_dlist_insert_at()
482 		sys_dnode_t *pos = sys_dlist_peek_head(list);  in sys_dlist_insert_at()
485 			pos = sys_dlist_peek_next(list, pos);  in sys_dlist_insert_at()
490 			sys_dlist_append(list, node);  in sys_dlist_insert_at()
496  * @brief remove a specific node from a list
499  * from a list. However, unlike :c:func:`sys_dlist_remove()`, this routine
504  * The list is implicit from the node. The node must be part of a list.
519  * @brief remove a specific node from a list
521  * The list is implicit from the node. The node must be part of a list.
538  * @brief get the first node in a list
542  * @param list the doubly-linked list to operate on
544  * @return the first node in the list, NULL if list is empty
547 static inline sys_dnode_t *sys_dlist_get(sys_dlist_t *list)  in sys_dlist_get()  argument
551 	if (!sys_dlist_is_empty(list)) {  in sys_dlist_get()
552 		node = list->head;  in sys_dlist_get()
560  * @brief Compute the size of the given list in O(n) time
562  * @param list A pointer on the list
564  * @return an integer equal to the size of the list, or 0 if empty
566 static inline size_t sys_dlist_len(sys_dlist_t *list)  in sys_dlist_len()  argument
571 	SYS_DLIST_FOR_EACH_NODE(list, node) {  in sys_dlist_len()