1 /*
2 * Copyright (c) 2021 Chipsea Technologies (Shenzhen) Corp., Ltd. All rights reserved.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15 #ifndef _WB_CO_LIST_H
16 #define _WB_CO_LIST_H
17
18 #include "wb_co_int.h"
19 #include "wb_co_bool.h"
20 // for NULL and size_t
21 #include <stddef.h>
22
23 // for __INLINE
24 #include "compiler.h"
25
26 /// structure of a list element header
27 struct co_list_hdr
28 {
29 /// Pointer to the next element in the list
30 struct co_list_hdr *next;
31 };
32
33 /// structure of a list
34 struct co_list
35 {
36 /// pointer to first element of the list
37 struct co_list_hdr *first;
38 /// pointer to the last element
39 struct co_list_hdr *last;
40 };
41
42
43 /*
44 * FUNCTION DECLARATIONS
45 ****************************************************************************************
46 */
47 /**
48 ****************************************************************************************
49 * @brief Initialize a list to defaults values.
50 * @param[in] list Pointer to the list structure.
51 ****************************************************************************************
52 */
53 void co_list_init(struct co_list *list);
54
55 /**
56 ****************************************************************************************
57 * @brief Initialize a pool to default values, and initialize the relative free list.
58 *
59 * @param[in] list Pointer to the list structure
60 * @param[in] pool Pointer to the pool to be initialized
61 * @param[in] elmt_size Size of one element of the pool
62 * @param[in] elmt_cnt Nb of elements available in the pool
63 * @param[in] default_value Pointer to the default value of each element (may be NULL)
64 ****************************************************************************************
65 */
66 void co_list_pool_init(struct co_list *list,
67 void *pool,
68 size_t elmt_size,
69 uint32_t elmt_cnt,
70 void *default_value);
71
72 /**
73 ****************************************************************************************
74 * @brief Add an element as last on the list.
75 *
76 * @param[in] list Pointer to the list structure
77 * @param[in] list_hdr Pointer to the header to add at the end of the list
78 ****************************************************************************************
79 */
80 void co_list_push_back(struct co_list *list,
81 struct co_list_hdr *list_hdr);
82
83 /**
84 ****************************************************************************************
85 * @brief Add an element as first on the list.
86 *
87 * @param[in] list Pointer to the list structure
88 * @param[in] list_hdr Pointer to the header to add at the beginning of the list
89 ****************************************************************************************
90 */
91 void co_list_push_front(struct co_list *list,
92 struct co_list_hdr *list_hdr);
93 /**
94 ****************************************************************************************
95 * @brief Extract the first element of the list.
96 *
97 * @param[in] list Pointer to the list structure
98 *
99 * @return The pointer to the element extracted, and NULL if the list is empty.
100 ****************************************************************************************
101 */
102 struct co_list_hdr *co_list_pop_front(struct co_list *list);
103
104 /**
105 ****************************************************************************************
106 * @brief Search for a given element in the list, and extract it if found.
107 *
108 * @param[in] list Pointer to the list structure
109 * @param[in] list_hdr Pointer to the searched element
110 *
111 * @return CO_EMPTY if the list is empty, CO_FAIL if the element not found in the list,
112 * CO_OK else.
113 ****************************************************************************************
114 */
115 void co_list_extract(struct co_list *list,
116 struct co_list_hdr *list_hdr);
117
118 /**
119 ****************************************************************************************
120 * @brief Searched a given element in the list.
121 *
122 * @param[in] list Pointer to the list structure
123 * @param[in] list_hdr Pointer to the searched element
124 *
125 * @return true if the element is found in the list, false otherwise
126 ****************************************************************************************
127 */
128 bool co_list_find(struct co_list *list,
129 struct co_list_hdr *list_hdr);
130
131 /**
132 ****************************************************************************************
133 * @brief Insert an element in a sorted list.
134 *
135 * This primitive use a comparison function from the parameter list to select where the
136 * element must be inserted.
137 *
138 * @param[in] list Pointer to the list.
139 * @param[in] element Pointer to the element to insert.
140 * @param[in] cmp Comparison function (return true if first element has to be inserted
141 * before the second one).
142 *
143 * @return Pointer to the element found and removed (NULL otherwise).
144 ****************************************************************************************
145 */
146 void co_list_insert(struct co_list * const list,
147 struct co_list_hdr * const element,
148 bool (*cmp)(struct co_list_hdr const *elementA,
149 struct co_list_hdr const *elementB));
150
151 /**
152 ****************************************************************************************
153 * @brief Insert an element in a sorted list after the provided element.
154 *
155 * This primitive use a comparison function from the parameter list to select where the
156 * element must be inserted.
157 *
158 * @param[in] list Pointer to the list.
159 * @param[in] prev_element Pointer to the element to find in the list
160 * @param[in] element Pointer to the element to insert.
161 *
162 * If prev_element is not found, the provided element is not inserted
163 ****************************************************************************************
164 */
165 void co_list_insert_after(struct co_list * const list,
166 struct co_list_hdr * const prev_element,
167 struct co_list_hdr * const element);
168
169 /**
170 ****************************************************************************************
171 * @brief Insert an element in a sorted list before the provided element.
172 *
173 * This primitive use a comparison function from the parameter list to select where the
174 * element must be inserted.
175 *
176 * @param[in] list Pointer to the list.
177 * @param[in] next_element Pointer to the element to find in the list
178 * @param[in] element Pointer to the element to insert.
179 *
180 * If next_element is not found, the provided element is not inserted
181 ****************************************************************************************
182 */
183 void co_list_insert_before(struct co_list * const list,
184 struct co_list_hdr * const next_element,
185 struct co_list_hdr * const element);
186
187 /**
188 ****************************************************************************************
189 * @brief Concatenate two lists.
190 * The resulting list is the list passed as the first parameter. The second list is
191 * emptied.
192 *
193 * @param[in] list1 First list (will get the result of the concatenation)
194 * @param[in] list2 Second list (will be emptied after the concatenation)
195 ****************************************************************************************
196 */
197 void co_list_concat(struct co_list *list1, struct co_list *list2);
198
199 /**
200 ****************************************************************************************
201 * @brief Remove the element in the list after the provided element.
202 *
203 * This primitive removes an element in the list. It is assume that element is part of
204 * the list.
205 *
206 * @param[in] list Pointer to the list.
207 * @param[in] prev_element Pointer to the previous element.
208 * NULL if @p element is the first element in the list
209 * @param[in] element Pointer to the element to remove.
210 *
211 ****************************************************************************************
212 */
213 void co_list_remove(struct co_list *list,
214 struct co_list_hdr *prev_element,
215 struct co_list_hdr *element);
216
217 /**
218 ****************************************************************************************
219 * @brief Count number of elements present in the list
220 *
221 * @param list Pointer to the list structure
222 *
223 * @return Number of elements present in the list
224 ****************************************************************************************
225 */
226 uint16_t co_list_size(struct co_list *list);
227
228 /**
229 ****************************************************************************************
230 * @brief Test if the list is empty.
231 *
232 * @param[in] list Pointer to the list structure.
233 *
234 * @return true if the list is empty, false else otherwise.
235 ****************************************************************************************
236 */
co_list_is_empty(const struct co_list * const list)237 __INLINE bool co_list_is_empty(const struct co_list *const list)
238 {
239 bool listempty;
240 listempty = (list->first == NULL);
241 return (listempty);
242 }
243
244 /**
245 ****************************************************************************************
246 * @brief Return the number of element of the list.
247 *
248 * @param[in] list Pointer to the list structure.
249 *
250 * @return The number of elements in the list.
251 ****************************************************************************************
252 */
253 uint32_t co_list_cnt(const struct co_list *const list);
254
255 /**
256 ****************************************************************************************
257 * @brief Pick the first element from the list without removing it.
258 *
259 * @param[in] list Pointer to the list structure.
260 *
261 * @return First element address. Returns NULL pointer if the list is empty.
262 ****************************************************************************************
263 */
co_list_pick(const struct co_list * const list)264 __INLINE struct co_list_hdr *co_list_pick(const struct co_list *const list)
265 {
266 return(list->first);
267 }
268
269 /**
270 ****************************************************************************************
271 * @brief Pick the last element from the list without removing it.
272 *
273 * @param[in] list Pointer to the list structure.
274 *
275 * @return Last element address. Returns invalid value if the list is empty.
276 ****************************************************************************************
277 */
co_list_pick_last(const struct co_list * const list)278 __INLINE struct co_list_hdr *co_list_pick_last(const struct co_list *const list)
279 {
280 return(list->last);
281 }
282
283 /**
284 ****************************************************************************************
285 * @brief Return following element of a list element.
286 *
287 * @param[in] list_hdr Pointer to the list element.
288 *
289 * @return The pointer to the next element.
290 ****************************************************************************************
291 */
co_list_next(const struct co_list_hdr * const list_hdr)292 __INLINE struct co_list_hdr *co_list_next(const struct co_list_hdr *const list_hdr)
293 {
294 return(list_hdr->next);
295 }
296
297 #endif // _WB_CO_LIST_H
298