- explain functions in list.h
- let lxc_list_len() return size_t instead of int
Signed-off-by: Christian Brauner <christian.brau...@mailbox.org>
---
I'm working on some stuff that employs struct lxc_list. I already previously
found that list.h lacked some short documentation so here it is. Adding this
documentation might be considered tmi but I think that it really eases
transitioning into a codebase a lot to have a few lines and common idioms even
for quite simple stuff such as circular linked lists here.
src/lxc/list.h | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 59 insertions(+), 2 deletions(-)
diff --git a/src/lxc/list.h b/src/lxc/list.h
index 2d8a2a8..3458b86 100644
--- a/src/lxc/list.h
+++ b/src/lxc/list.h
@@ -32,42 +32,71 @@ struct lxc_list {
#define lxc_init_list(l) { .next = l, .prev = l }
+/*
+ * Iterate through an lxc list. An example for an idiom would be:
+ *
+ * struct lxc_list *iterator;
+ * type *tmp; // where "type" can be an int, char * etc.
+ * lxc_list_for_each(iterator, list) {
+ * tmp = iterator->elem;
+ * // Do stuff with tmp.
+ * }
+ * free(iterator);
+ */
#define lxc_list_for_each(__iterator, __list) \
for (__iterator = (__list)->next; \
__iterator != __list; \
__iterator = __iterator->next)
+/*
+ * Iterate safely through an lxc list. An example for an appropriate use case
+ * would be:
+ *
+ * struct lxc_list *iterator;
+ * lxc_list_for_each_safe(iterator, list, list->next) {
+ * tmp = iterator->elem;
+ * // Do stuff with tmp.
+ * }
+ * free(iterator);
+ */
#define lxc_list_for_each_safe(__iterator, __list, __next) \
for (__iterator = (__list)->next, __next = __iterator->next; \
__iterator != __list; \
__iterator = __next, __next = __next->next)
+/* Initalize list. */
static inline void lxc_list_init(struct lxc_list *list)
{
list->elem = NULL;
list->next = list->prev = list;
}
+/* Add an element to a list. See lxc_list_add() and lxc_list_add_tail() for an
+ * idiom. */
static inline void lxc_list_add_elem(struct lxc_list *list, void *elem)
{
list->elem = elem;
}
+/* Retrieve first element of list. */
static inline void *lxc_list_first_elem(struct lxc_list *list)
{
return list->next->elem;
}
+/* Retrieve last element of list. */
static inline void *lxc_list_last_elem(struct lxc_list *list)
{
return list->prev->elem;
}
+/* Determine if list is empty. */
static inline int lxc_list_empty(struct lxc_list *list)
{
return list == list->next;
}
+/* Workhorse to be called from lxc_list_add() and lxc_list_add_tail(). */
static inline void __lxc_list_add(struct lxc_list *new,
struct lxc_list *prev,
struct lxc_list *next)
@@ -78,17 +107,44 @@ static inline void __lxc_list_add(struct lxc_list *new,
prev->next = new;
}
+/*
+ * Idiom to add an element to the beginning of an lxc list:
+ *
+ * struct lxc_list *tmp = malloc(sizeof(*tmp));
+ * if (tmp == NULL)
+ * return 1;
+ * lxc_list_add_elem(tmp, elem);
+ * lxc_list_add(list, tmp);
+ */
static inline void lxc_list_add(struct lxc_list *head, struct lxc_list *list)
{
__lxc_list_add(list, head, head->next);
}
+/*
+ * Idiom to add an element to the end of an lxc list:
+ *
+ * struct lxc_list *tmp = malloc(sizeof(*tmp));
+ * if (tmp == NULL)
+ * return 1;
+ * lxc_list_add_elem(tmp, elem);
+ * lxc_list_add_tail(list, tmp);
+ */
static inline void lxc_list_add_tail(struct lxc_list *head,
struct lxc_list *list)
{
__lxc_list_add(list, head->prev, head);
}
+/*
+ * Idiom to free an lxc list:
+ *
+ * lxc_list_for_each_safe(iterator, list, list->next) {
+ * lxc_list_del(iterator);
+ * free(iterator);
+ * }
+ * free(iterator);
+ */
static inline void lxc_list_del(struct lxc_list *list)
{
struct lxc_list *next, *prev;
@@ -99,9 +155,10 @@ static inline void lxc_list_del(struct lxc_list *list)
prev->next = next;
}
-static inline int lxc_list_len(struct lxc_list *list)
+/* Return length of the list. */
+static inline size_t lxc_list_len(struct lxc_list *list)
{
- int i = 0;
+ size_t i = 0;
struct lxc_list *iter;
lxc_list_for_each(iter, list) {
i++;
--
2.6.3
_______________________________________________
lxc-devel mailing list
lxc-devel@lists.linuxcontainers.org
http://lists.linuxcontainers.org/listinfo/lxc-devel
