[lxc-devel] [PATCH] Add concise explanations

[Stéphane Graber]

On Thu, Dec 10, 2015 at 05:26:18AM +0100, Christian Brauner wrote:
> - explain functions in list.h
> - let lxc_list_len() return size_t instead of int
> 
> Signed-off-by: Christian Brauner <christian.brauner at mailbox.org>

Acked-by: Stéphane Graber <stgraber at ubuntu.com>

> ---
> 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 at lists.linuxcontainers.org
> http://lists.linuxcontainers.org/listinfo/lxc-devel

-- 
Stéphane Graber
Ubuntu developer
http://www.ubuntu.com
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: Digital signature
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20151211/cb6f6132/attachment-0001.sig>