Contiki-NG
circular-list.h
1 /*
2  * Copyright (c) 2017, George Oikonomou - http://www.spd.gr
3  * Copyright (c) 2017, James Pope
4  * All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions
8  * are met:
9  *
10  * 1. Redistributions of source code must retain the above copyright
11  * notice, this list of conditions and the following disclaimer.
12  * 2. Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in the
14  * documentation and/or other materials provided with the distribution.
15  * 3. Neither the name of the copyright holder nor the names of its
16  * contributors may be used to endorse or promote products derived
17  * from this software without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
22  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
23  * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
24  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
25  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
28  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
30  * OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 /*---------------------------------------------------------------------------*/
33 /** \addtogroup data
34  * @{
35  *
36  * \defgroup circular-singly-linked-list Circular, singly-linked list
37  *
38  * This library provides functions for the creation and manipulation of
39  * circular, singly-linked lists.
40  *
41  * A circular, singly-linked list is declared using the CIRCULAR_LIST macro.
42  * Elements must be allocated by the calling code and must be of a C struct
43  * datatype. In this struct, the first field must be a pointer called \e next.
44  * This field will be used by the library to maintain the list. Application
45  * code must not modify this field directly.
46  *
47  * Functions that modify the list (add / remove) will, in the general case,
48  * update the list's head and item order. If you call one of these functions
49  * as part of a list traversal, it is advised to stop / restart traversing
50  * after the respective function returns.
51  *
52  * This library is not safe to be used within an interrupt context.
53  * @{
54  */
55 /*---------------------------------------------------------------------------*/
56 #ifndef CIRCULAR_LIST_H_
57 #define CIRCULAR_LIST_H_
58 /*---------------------------------------------------------------------------*/
59 #include "contiki.h"
60 
61 #include <stdint.h>
62 #include <stdbool.h>
63 #include <string.h>
64 /*---------------------------------------------------------------------------*/
65 /**
66  * \brief Define a circular, singly-linked list.
67  *
68  * This macro defines a circular, singly-linked list.
69  *
70  * The datatype for elements must be a C struct. The struct's first member must
71  * be a pointer called \e next. This is used internally by the library to
72  * maintain data structure integrity and must not be modified directly by
73  * application code.
74  *
75  * \param name The name of the circular, singly-linked list.
76  */
77 #define CIRCULAR_LIST(name) \
78  static void *name##_circular_list = NULL; \
79  static circular_list_t name = (circular_list_t)&name##_circular_list
80 /*---------------------------------------------------------------------------*/
81 /**
82  * \brief The circular, singly-linked list datatype
83  */
84 typedef void **circular_list_t;
85 /*---------------------------------------------------------------------------*/
86 /**
87  * \brief Initialise a circular, singly-linked list.
88  * \param cl The circular, singly-linked list.
89  */
91 
92 /**
93  * \brief Return the tail of a circular, singly-linked list.
94  * \param cl The circular, singly-linked list.
95  * \return A pointer to the list's head, or NULL if the list is empty
96  */
98 
99 /**
100  * \brief Return the tail of a circular, singly-linked list.
101  * \param cl The circular, singly-linked list.
102  * \return A pointer to the list's tail, or NULL if the list is empty
103  */
105 
106 /**
107  * \brief Add an element to a circular, singly-linked list.
108  * \param cl The circular, singly-linked list.
109  * \param element A pointer to the element to be added.
110  *
111  * The caller should make no assumptions as to the position in the list of the
112  * new element.
113  *
114  * After this function returns, the list's head is not guaranteed to be the
115  * same as it was before the addition.
116  *
117  * Calling this function will update the list's head and item order. If you
118  * call this function as part of a list traversal, it is advised to stop
119  * traversing after this function returns.
120  */
121 void circular_list_add(circular_list_t cl, void *element);
122 
123 /**
124  * \brief Remove an element from a circular, singly-linked list.
125  * \param cl The circular, singly-linked list.
126  * \param element A pointer to the element to be removed.
127  *
128  * After this function returns, the list's head is not guaranteed to be the
129  * same as it was before the addition.
130  *
131  * Calling this function will update the list's head and item order. If you
132  * call this function as part of a list traversal, it is advised to stop
133  * traversing after this function returns.
134  */
135 void circular_list_remove(circular_list_t cl, void *element);
136 
137 /**
138  * \brief Get the length of a circular, singly-linked list.
139  * \param cl The circular, singly-linked list.
140  * \return The number of elements in the list
141  */
142 unsigned long circular_list_length(circular_list_t cl);
143 
144 /**
145  * \brief Determine whether a circular, singly-linked list is empty.
146  * \param cl The circular, singly-linked list.
147  * \retval true The list is empty
148  * \retval false The list is not empty
149  */
151 /*---------------------------------------------------------------------------*/
152 #endif /* CIRCULAR_LIST_H_ */
153 /*---------------------------------------------------------------------------*/
154 /**
155  * @}
156  * @}
157  */
void circular_list_init(circular_list_t cl)
Initialise a circular, singly-linked list.
Definition: circular-list.c:53
unsigned long circular_list_length(circular_list_t cl)
Get the length of a circular, singly-linked list.
void * circular_list_head(circular_list_t cl)
Return the tail of a circular, singly-linked list.
Definition: circular-list.c:59
void circular_list_add(circular_list_t cl, void *element)
Add an element to a circular, singly-linked list.
void * circular_list_tail(circular_list_t cl)
Return the tail of a circular, singly-linked list.
Definition: circular-list.c:65
bool circular_list_is_empty(circular_list_t cl)
Determine whether a circular, singly-linked list is empty.
void ** circular_list_t
The circular, singly-linked list datatype.
Definition: circular-list.h:84
void circular_list_remove(circular_list_t cl, void *element)
Remove an element from a circular, singly-linked list.
Definition: circular-list.c:79