tools/cfzy/libconfizery/cfzy_list.h

   1 /*
   2  * Copyright (c) 2013, Olivier MATZ <zer0@droids-corp.org>
   3  * All rights reserved.
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are met:
   6  *
   7  *     * Redistributions of source code must retain the above copyright
   8  *       notice, this list of conditions and the following disclaimer.
   9  *     * Redistributions in binary form must reproduce the above copyright
  10  *       notice, this list of conditions and the following disclaimer in the
  11  *       documentation and/or other materials provided with the distribution.
  12  *     * Neither the name of the University of California, Berkeley nor the
  13  *       names of its contributors may be used to endorse or promote products
  14  *       derived from this software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
  17  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
  20  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  22  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  25  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 #ifndef _CFZY_LIST_H_
  29 #define _CFZY_LIST_H_
  30
  31 /**
  32  * @file
  33  * Confizery List
  34  *
  35  * This module is a list implementation, based on TAILQ from
  36  * sys/queue.h -see queue(3)-. It handles the allocation of chaining
  37  * structure so any kind of element can be chained.
  38  *
  39  * To be really useful, this API must be used in conjonction with the
  40  * TAILQ_* macros. For instance, to browse the list:
  41  *
  42  *      struct cfzy_list_elt *e;
  43  *      TAILQ_FOREACH(e, list_head, next) {
  44  *              obj = e->ptr;
  45  *              ...
  46  *      }
  47  */
  48
  49 #include <sys/queue.h>
  50
  51 /**
  52  * A list head
  53  */
  54 TAILQ_HEAD(cfzy_list_head, cfzy_list_elt);
  55
  56 /**
  57  * A list element, used to chain objects together. This structure is
  58  * allocated by cfzy_list_add().
  59  */
  60 struct cfzy_list_elt {
  61         TAILQ_ENTRY(cfzy_list_elt) next;
  62         void *ptr;
  63 };
  64
  65 /**
  66  * Insert an element at the tail of the list
  67  *
  68  * Allocate a cfzy_list_elt structure, set its ptr field and insert it
  69  * at the tail of the list.
  70  *
  71  * @param list
  72  *   List head to insert the element
  73  * @param ptr
  74  *   Pointer to the object that will be referenced by list_elt->ptr
  75  * @return
  76  *   0 on succes, and negative on error
  77  */
  78 int cfzy_list_add_tail(struct cfzy_list_head *list, void *ptr);
  79
  80 /**
  81  * Insert an element at the head of the list
  82  *
  83  * Allocate a cfzy_list_elt structure, set its ptr field and insert it
  84  * at the head of the list.
  85  *
  86  * @param list
  87  *   List head to insert the element
  88  * @param ptr
  89  *   Pointer to the object that will be referenced by list_elt->ptr
  90  * @return
  91  *   0 on succes, and negative on error
  92  */
  93 int cfzy_list_add_head(struct cfzy_list_head *list, void *ptr);
  94
  95 /**
  96  * Remove an element from the list
  97  *
  98  * Unchain the cfzy_list_elt structure and free it.
  99  *
 100  * @param list
 101  *   List head to insert the element
 102  * @param elt
 103  *   List element
 104  */
 105 void cfzy_list_del(struct cfzy_list_head *list, struct cfzy_list_elt *elt);
 106
 107 /**
 108  * Check if an element is in the list
 109  *
 110  * Browse the list and check if there is already an cfzy_list_elt
 111  * structure referencing ptr.
 112  *
 113  * @param list
 114  *   List head
 115  * @param ptr
 116  *   Pointer to the element
 117  * @return
 118  *   1 if the element is in list, else 0
 119  */
 120 int cfzy_list_elt_is_in_list(const struct cfzy_list_head *list, const void *ptr);
 121
 122 /**
 123  * Allocate a new list
 124  *
 125  * @return
 126  *   Pointer to the new list head, or NULL on error
 127  */
 128 struct cfzy_list_head *cfzy_list_alloc(void);
 129
 130 /**
 131  * Free a list
 132  *
 133  * Free all cfzy_list_elt of the list using the free_fct if provided,
 134  * then free the cfzy_list_head structure.
 135  *
 136  * @param list
 137  *   List head pointer
 138  * @param free_fct
 139  *   Function to free an element
 140  */
 141 void cfzy_list_free(struct cfzy_list_head *list, void (*free_fct)(void *));
 142
 143 #endif /* _CFZY_LIST_H_ */