commit 29edca9fb80e749f53b8f6bbb3509dbc40d699a0
parent 84b443f93828340e0da7e225c1a35a29995b6175
Author: Evgeny Grin (Karlson2k) <k2k@drgrin.dev>
Date: Mon, 22 Dec 2025 16:18:13 +0100
mhd_dlinked_list.h: corrected some doxy and asserts
Diffstat:
1 file changed, 60 insertions(+), 34 deletions(-)
diff --git a/src/mhd2/mhd_dlinked_list.h b/src/mhd2/mhd_dlinked_list.h
@@ -38,10 +38,10 @@
/**
* @file src/mhd2/mhd_dlinked_list.h
- * @brief Double-linked list macros and declarations
+ * @brief Doubly-linked list macros and declarations
* @author Karlson2k (Evgeny Grin)
*
- * Double-linked list macros help create and manage the chain of objects
+ * Doubly-linked list macros help create and manage the chain of objects
* connected via inter-object pointers (named here @a links_name), while
* the list is held by the owner within the helper (named here @a list_name).
*/
@@ -55,10 +55,10 @@
#include "mhd_assert.h"
-/* This header defines macros for handling double-linked lists of object.
+/* This header defines macros for handling doubly-linked lists of objects.
The pointers to the first and the last objects in the list are held in
the "owner".
- The list member objects links to each other via "next" and "prev" links.
+ The list member object links to each other via "next" and "prev" links.
Each member object can be part of several lists. For example, connections are
maintained in "all connections" and "need to process" lists simultaneously.
List member can be removed from the list or inserted to the list at any
@@ -67,9 +67,10 @@
the name of inter-links. However, it is possible to use different names.
For example, connections can be removed from "all connections" list and
moved the "clean up" list using the same internal links "all connections".
- As this is a double-linked list, it can be walked from begin to the end and
- in the opposite direction.
- The list is compatible only with "struct" types.
+ As this is a doubly-linked list, it can be walked rom the beginning to the
+ end and in the opposite direction.
+ The list is designed to work with struct tags as a contained and container
+ objects.
*/
/* Helpers */
@@ -82,12 +83,12 @@
/* Names */
/**
- * The name of struct that hold the list in the owner object
+ * The name of struct that holds the list in the owner object
*/
#define mhd_DLNKDL_LIST_TYPE(base_name) mhd_DLNKDL_LIST_TYPE_ (base_name)
/**
- * The name of struct that links between the list members
+ * The name of the struct that holds the links between list members
*/
#define mhd_DLNKDL_LINKS_TYPE(base_name) mhd_DLNKDL_LINKS_TYPE_ (base_name)
@@ -95,7 +96,7 @@
/**
* Template for declaration of the list helper struct
- * @param l_type the name of the struct objects that list links
+ * @param l_type the struct tag name of objects that list links
*/
#define mhd_DLINKEDL_LIST_DEF(l_type) \
mhd_DLNKDL_LIST_TYPE (l_type) { /* Holds the list in the owner */ \
@@ -105,7 +106,7 @@
/**
* Template for declaration of links helper struct
- * @param l_type the name of the struct objects that list links
+ * @param l_type the struct tag name of objects that list links
*/
#define mhd_DLINKEDL_LINKS_DEF(l_type) \
mhd_DLNKDL_LINKS_TYPE (l_type) { /* Holds the links in the members */ \
@@ -116,7 +117,7 @@
/**
* Template for declaration of list helper structs
- * @param l_type the name of the struct objects that list links
+ * @param l_type the struct tag name of objects that the list holds
*/
#define mhd_DLINKEDL_STRUCTS_DEFS(l_type) \
mhd_DLINKEDL_LIST_DEF (l_type); mhd_DLINKEDL_LINKS_DEF (l_type)
@@ -141,10 +142,10 @@
* of link object (in the list members). */
/**
- * Initialise the double linked list pointers in the list object using
- * the directly pointer to the list
+ * Initialise the doubly linked list pointers in the list object using
+ * the direct pointer to the list
+ * @warning arguments are evaluated multiple times
* @param p_list the pointer to the list
- * @param l_name the name of the list
*/
#define mhd_DLINKEDL_INIT_LIST_D(p_list) \
do {(p_list)->first = NULL; (p_list)->last = NULL;} while (0)
@@ -152,10 +153,11 @@
/**
* Insert object into the first position in the list using direct pointer
* to the list
+ * @warning arguments are evaluated multiple times
* @param p_list the pointer to the list
* @param p_obj the pointer to the new list member object to insert to
- * the @a l_name list
- * @param l_name the name of the list
+ * the @a links_name list
+ * @param links_name the name of the links member in the @a p_obj
*/
#define mhd_DLINKEDL_INS_FIRST_D(p_list,p_obj,links_name) do { \
mhd_assert (NULL == (p_obj)->links_name.prev); \
@@ -164,6 +166,7 @@
mhd_assert ((p_obj) != (p_list)->last); \
if (NULL != (p_list)->first) \
{ mhd_assert (NULL == (p_list)->first->links_name.prev); \
+ mhd_assert (NULL == (p_list)->last->links_name.next); \
mhd_assert ((p_obj) != (p_list)->first->links_name.next); \
mhd_assert (NULL != (p_list)->last); \
((p_obj)->links_name.next = (p_list)->first) \
@@ -175,18 +178,20 @@
/**
* Insert object into the last position in the list using direct pointer
* to the list
+ * @warning arguments are evaluated multiple times
* @param p_list the pointer to the list
* @param p_obj the pointer to the new list member object to insert to
- * the @a l_name list
- * @param l_name the name of the list
+ * the @a links_name list
+ * @param links_name the name of the links member in the @a p_obj
*/
#define mhd_DLINKEDL_INS_LAST_D(p_list,p_obj,links_name) do { \
mhd_assert (NULL == (p_obj)->links_name.prev); \
mhd_assert (NULL == (p_obj)->links_name.next); \
mhd_assert ((p_obj) != (p_list)->first); \
mhd_assert ((p_obj) != (p_list)->last); \
- if (NULL != (p_list)->last) \
- { mhd_assert (NULL == (p_list)->last->links_name.next); \
+ if (NULL != (p_list)->last) \
+ { mhd_assert (NULL == (p_list)->last->links_name.next); \
+ mhd_assert (NULL == (p_list)->first->links_name.prev); \
mhd_assert ((p_obj) != (p_list)->last->links_name.prev); \
mhd_assert (NULL != (p_list)->first); \
((p_obj)->links_name.prev = (p_list)->last) \
@@ -197,15 +202,18 @@
/**
* Remove object from the list using direct pointer to the list
+ * @warning arguments are evaluated multiple times
* @param p_list the pointer to the list
- * @param p_own the pointer to the existing @a l_name list member object
+ * @param p_obj the pointer to the existing list member object
* to remove from the list
- * @param l_name the name of the list
+ * @param links_name the name of the links member in the @a p_obj
*/
#define mhd_DLINKEDL_DEL_D(p_list,p_obj,links_name) do { \
mhd_assert (NULL != (p_list)->first); \
mhd_assert (NULL != (p_list)->last); \
- mhd_assert ((p_obj) != (p_obj)->links_name.prev); \
+ mhd_assert (NULL == (p_list)->first->links_name.prev); \
+ mhd_assert (NULL == (p_list)->last->links_name.next); \
+ mhd_assert ((p_obj) != (p_obj)->links_name.prev); \
mhd_assert ((p_list)->last != (p_obj)->links_name.prev); \
mhd_assert ((p_obj) != (p_obj)->links_name.next); \
mhd_assert ((p_list)->first != (p_obj)->links_name.next); \
@@ -227,7 +235,7 @@
(p_obj)->links_name.next = NULL; } while (0)
/**
- * Get the fist object in the list using direct pointer to the list
+ * Get the first object in the list using direct pointer to the list
*/
#define mhd_DLINKEDL_GET_FIRST_D(p_list) ((p_list)->first)
@@ -244,17 +252,20 @@
/* Initialisers */
/**
- * Initialise the double linked list pointers in the owner object
- * @param p_own the pointer to the owner object with the @a l_name list
- * @param l_name the name of the list
+ * Initialise the doubly linked list pointers in the owner object
+ * @warning arguments are evaluated multiple times
+ * @param p_own the pointer to the owner object with the @a list_name list
+ * @param list_name the name of the list
*/
#define mhd_DLINKEDL_INIT_LIST(p_own,list_name) \
mhd_DLINKEDL_INIT_LIST_D (&((p_own)->list_name))
/**
- * Initialise the double linked list pointers in the list member object
- * @param p_obj the pointer to the future member object of the @a l_name list
- * @param l_name the name of the list
+ * Initialise the doubly linked list pointers in the list member object
+ * @warning arguments are evaluated multiple times
+ * @param p_obj the pointer to the future member object of
+ * the @a links_name list
+ * @param links_name the name of the links member in the @a p_obj
*/
#define mhd_DLINKEDL_INIT_LINKS(p_obj,links_name) \
do {(p_obj)->links_name.prev = NULL; \
@@ -264,6 +275,7 @@
/**
* Insert object into the first position in the list
+ * @warning arguments are evaluated multiple times
* @param p_own the pointer to the owner object with the @a l_name list
* @param p_obj the pointer to the new list member object to insert to
* the @a l_name list
@@ -274,6 +286,7 @@
/**
* Insert object into the last position in the list
+ * @warning arguments are evaluated multiple times
* @param p_own the pointer to the owner object with the @a l_name list
* @param p_obj the pointer to the new list member object to insert to
* the @a l_name list
@@ -284,8 +297,9 @@
/**
* Remove object from the list
- * @param p_mem the pointer to the owner object with the @a l_name list
- * @param p_own the pointer to the existing @a l_name list member object
+ * @warning arguments are evaluated multiple times
+ * @param p_own the pointer to the owner object with the @a l_name list
+ * @param p_obj the pointer to the existing @a l_name list member object
* to remove from the list
* @param l_name the same name for the list and the links
*/
@@ -295,24 +309,36 @@
/* List iterations */
/**
- * Get the fist object in the list
+ * Get the first object in the list
+ * @warning arguments are evaluated multiple times
+ * @param p_own the pointer to the owner object with the @a list_name list
+ * @param list_name the name of the list
*/
#define mhd_DLINKEDL_GET_FIRST(p_own,list_name) \
mhd_DLINKEDL_GET_FIRST_D (&((p_own)->list_name))
/**
* Get the last object in the list
+ * @warning arguments are evaluated multiple times
+ * @param p_own the pointer to the owner object with the @a list_name list
+ * @param list_name the name of the list
*/
#define mhd_DLINKEDL_GET_LAST(p_own,list_name) \
mhd_DLINKEDL_GET_LAST_D (&((p_own)->list_name))
/**
* Get the next object in the list
+ * @warning arguments are evaluated multiple times
+ * @param p_obj the pointer to the existing @a links_name list member object
+ * @param links_name the name of the links member in the @a p_obj
*/
#define mhd_DLINKEDL_GET_NEXT(p_obj,links_name) ((p_obj)->links_name.next)
/**
* Get the previous object in the list
+ * @warning arguments are evaluated multiple times
+ * @param p_obj the pointer to the existing @a links_name list member object
+ * @param links_name the name of the links member in the @a p_obj
*/
#define mhd_DLINKEDL_GET_PREV(p_obj,links_name) ((p_obj)->links_name.prev)
