sys: dlist: add API to split lists

Add a constant-time operation that splits a list into a portion before a
node and the portion starting at the node, moving the portion before the
node to the end of a different list and leaving the original list
starting at the node.

Add a constant-time list join operation to append an existing list to a
different list.

This supports use cases where a dlist is split at some point
(e.g. timers that have reached their deadline), so that the extracted
elements can be processed without affecting content added to the
dlist during processing.

Signed-off-by: Peter A. Bigot <[email protected]>

Author: pabigot

include/misc/dlist.h

@@ -552,6 +552,68 @@ static inline sys_dnode_t *sys_dlist_get(sys_dlist_t *list)
 	return node;
 }
 
+/**
+ * @brief place the contents of one list at the end of another list.
+ *
+ * The @p to and @p from lists must be distinct.  On completion @p from
+ * will be empty, all of its elements having been appended in original
+ * order to @p to.
+ *
+ * @param to a list, possibly non-empty, to which from will be appended
+ * @param from the list providing the elements to append
+ *
+ * @return N/A
+ */
+static inline void sys_dlist_join(sys_dlist_t *to,
+				  sys_dlist_t *from)
+{
+	if (!sys_dlist_is_empty(from)) {
+		from->head->prev = to->tail;
+		to->tail->next = from->head;
+
+		from->tail->next = to;
+		to->tail = from->tail;
+
+		sys_dlist_init(from);
+	}
+}
+
+/**
+ * @brief split a list at a node
+ *
+ * list will be updated to start at node.  Any nodes before node will
+ * be appended to prefix.
+ *
+ * This and other sys_dlist_*() functions are not thread safe.
+ *
+ * @param prefix a list to which items in @p list before @p node
+ * will be appended
+ * @param list a non-empty list
+ * @param node a node within @p list
+ *
+ * @return N/A
+ */
+static inline void sys_dlist_split(sys_dlist_t *prefix,
+				   sys_dlist_t *list,
+				   sys_dnode_t *node)
+{
+	sys_dnode_t *old_pfx_tail = prefix->tail;
+	sys_dnode_t *new_pfx_tail = node->prev;
+
+	if (sys_dlist_peek_head(list) == node) {
+		return;
+	}
+
+	list->head->prev = old_pfx_tail;
+	old_pfx_tail->next = list->head;
+
+	prefix->tail = new_pfx_tail;
+	new_pfx_tail->next = prefix;
+
+	list->head = node;
+	node->prev = list;
+}
+
 #ifdef __cplusplus
 }
 #endif

tests/kernel/common/src/dlist.c

@@ -8,6 +8,7 @@
 #include <misc/dlist.h>
 
 static sys_dlist_t test_list;
+static sys_dlist_t test_list2;
 
 struct container_node {
 	sys_dnode_t node;
@@ -281,6 +282,74 @@ void test_dlist(void)
 	zassert_true((verify_emptyness(&test_list)),
 		     "test_list should be empty");
 
+
+	/* Catenate an empty list to a non-empty list */
+	sys_dlist_append(&test_list, &test_node_1.node);
+	sys_dlist_init(&test_list2);
+	sys_dlist_join(&test_list, &test_list2);
+	zassert_true(sys_dlist_is_empty(&test_list2),
+		     "list2 not empty");
+	zassert_true((verify_tail_head(&test_list, &test_node_1.node,
+				       &test_node_1.node, true)),
+		     "test_list head/tail are wrong");
+
+	/* Catenate a non-empty list to an empty list moves elements. */
+	sys_dlist_join(&test_list2, &test_list);
+	zassert_true(sys_dlist_is_empty(&test_list),
+		     "list not empty");
+	zassert_true((verify_tail_head(&test_list2, &test_node_1.node,
+				       &test_node_1.node, true)),
+		     "test_list2 head/tail are wrong");
+
+	/* Catenate a non-empty list to a non-empty list moves elements. */
+	sys_dlist_append(&test_list, &test_node_2.node);
+	sys_dlist_append(&test_list, &test_node_3.node);
+	zassert_true((verify_tail_head(&test_list, &test_node_2.node,
+				       &test_node_3.node, false)),
+		     "test_list head/tail are wrong");
+	sys_dlist_join(&test_list2, &test_list);
+	zassert_true(sys_dlist_is_empty(&test_list),
+		     "list not empty");
+	zassert_true((verify_tail_head(&test_list2, &test_node_1.node,
+				       &test_node_3.node, false)),
+		     "test_list2 head/tail are wrong");
+	zassert_equal(test_node_1.node.next, &test_node_2.node,
+		      "node2 not after node1");
+	zassert_equal(test_node_2.node.prev, &test_node_1.node,
+		      "node1 not before node2");
+
+	/* Split list at head does nothing */
+	sys_dlist_split(&test_list, &test_list2, &test_node_1.node);
+	zassert_true(sys_dlist_is_empty(&test_list),
+		     "list not empty");
+
+	/* Split list after head moves */
+	sys_dlist_split(&test_list, &test_list2, &test_node_2.node);
+	zassert_true((verify_tail_head(&test_list, &test_node_1.node,
+				       &test_node_1.node, true)),
+		     "test_list head/tail are wrong");
+	zassert_true((verify_tail_head(&test_list2, &test_node_2.node,
+				       &test_node_3.node, false)),
+		     "test_list2 head/tail are wrong");
+
+	/* Split list after head moves */
+	sys_dlist_split(&test_list, &test_list2, &test_node_3.node);
+	zassert_true((verify_tail_head(&test_list, &test_node_1.node,
+				       &test_node_2.node, false)),
+		     "test_list head/tail are wrong");
+	zassert_true((verify_tail_head(&test_list2, &test_node_3.node,
+				       &test_node_3.node, true)),
+		     "test_list2 head/tail are wrong");
+
+	sys_dlist_remove(&test_node_1.node);
+	sys_dlist_remove(&test_node_2.node);
+	zassert_true(sys_dlist_is_empty(&test_list),
+		     "list not empty");
+
+	sys_dlist_remove(&test_node_3.node);
+	zassert_true(sys_dlist_is_empty(&test_list2),
+		     "list2 not empty");
+
 	/* test iterator from a node */
 	struct data_node {
 		sys_dnode_t node;