[processor-sdk/big-data-ipc-examples.git] / host_linux / simple_buffer_example / host / utils / List.h
1 /**
2 * @file List.h
3 *
4 * @brief Creates a doubly linked list. It works as utils for other
5 * modules
6 *
7 *
8 */
9 /*
10 * ============================================================================
11 *
12 * Copyright (c) 2008-2017, Texas Instruments Incorporated
13 *
14 * Redistribution and use in source and binary forms, with or without
15 * modification, are permitted provided that the following conditions
16 * are met:
17 *
18 * * Redistributions of source code must retain the above copyright
19 * notice, this list of conditions and the following disclaimer.
20 *
21 * * Redistributions in binary form must reproduce the above copyright
22 * notice, this list of conditions and the following disclaimer in the
23 * documentation and/or other materials provided with the distribution.
24 *
25 * * Neither the name of Texas Instruments Incorporated nor the names of
26 * its contributors may be used to endorse or promote products derived
27 * from this software without specific prior written permission.
28 *
29 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
30 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
31 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
32 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
33 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
34 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
35 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
36 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
37 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
38 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
39 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
40 * Contact information for paper mail:
41 * Texas Instruments
42 * Post Office Box 655303
43 * Dallas, Texas 75265
44 * Contact information:
45 * http://www-k.ext.ti.com/sc/technical-support/product-information-centers.htm?
46 * DCMP=TIHomeTracking&HQS=Other+OT+home_d_contact
47 * ============================================================================
48 *
49 */
53 #ifndef LIST_H_0XB734
54 #define LIST_H_0XB734
58 #if defined (__cplusplus)
59 extern "C" {
60 #endif
63 /* =============================================================================
64 * Macros and types
65 * =============================================================================
66 */
67 /*!
68 * @def List_traverse
69 * @brief Traverse the full list till the last element.
70 */
71 #define List_traverse(x,y) for(x = (List_Elem *)((List_Object *)y)->elem.next; \
72 (UInt32) x != (UInt32)&((List_Object *)y)->elem;\
73 x = x->next)
75 /*!
76 * @brief Structure defining object for the list element.
77 */
78 typedef struct List_Elem_tag {
79 struct List_Elem_tag * next; /*!< Pointer to the next element */
80 struct List_Elem_tag * prev; /*!< Pointer to the previous element */
81 } List_Elem;
83 /*!
84 * @brief Structure defining object for the list.
85 */
86 typedef struct List_Object_tag {
87 List_Elem elem;
88 /*!< Head pointing to next element */
89 } List_Object;
91 /*! @brief Defines List handle type */
92 typedef List_Object * List_Handle;
94 /*!
95 * @brief Structure defining params for the list.
96 */
97 typedef struct List_Params_tag {
98 UInt32 temp;
99 } List_Params;
102 /* =============================================================================
103 * APIs
104 * =============================================================================
105 */
106 /*!
107 * @brief Initialize this config-params structure with supplier-specified
108 * defaults before instance creation.
109 *
110 * @param params Instance config-params structure.
111 *
112 * @sa List_create
113 */
114 Void List_Params_init (List_Params * params);
116 /*!
117 * @brief Function to create a list object.
118 *
119 * @param params Pointer to list creation parameters. If NULL is passed,
120 * default parameters are used.
121 * @param eb Unused
122 *
123 * @retval List-handle Handle to the list object
124 *
125 * @sa List_delete
126 */
127 List_Handle List_create (List_Params * params, Error_Block *eb);
129 /*!
130 * @brief Function to delete a list object.
131 *
132 * @param handlePtr Pointer to the list handle
133 *
134 * @sa List_delete
135 */
136 Void List_delete (List_Handle * handlePtr);
138 /*!
139 * @brief Function to construct a list object. This function is used when
140 * memory for the list object is not to be allocated by the List
141 * API.
142 *
143 * @param obj Pointer to the list object to be constructed
144 * @param params Pointer to list construction parameters. If NULL is
145 * passed, default parameters are used.
146 *
147 * @sa List_destruct
148 */
149 Void List_construct (List_Object * obj, List_Params * params);
151 /*!
152 * @brief Function to destruct a list object.
153 *
154 * @param obj Pointer to the list object to be destructed
155 *
156 * @sa List_construct
157 */
158 Void List_destruct (List_Object * obj);
160 /*!
161 * @brief Function to clear element contents.
162 *
163 * @param elem Element to be cleared
164 *
165 * @sa
166 */
167 Void List_elemClear (List_Elem * elem);
169 /*!
170 * @brief Function to check if list is empty.
171 *
172 * @param handle Pointer to the list
173 *
174 * @retval TRUE List is empty
175 * @retval FALSE List is not empty
176 *
177 * @sa
178 */
179 Bool List_empty (List_Handle handle);
181 /*!
182 * @brief Function to get first element of List.
183 *
184 * @param handle Pointer to the list
185 *
186 * @retval NULL Operation failed
187 * @retval Valid-pointer Pointer to first element
188 *
189 * @sa List_put
190 */
191 Ptr List_get (List_Handle handle);
193 /*!
194 * @brief Function to insert element at the end of List.
195 *
196 * @param handle Pointer to the list
197 * @param elem Element to be inserted
198 *
199 * @sa List_get
200 */
201 Void List_put (List_Handle handle, List_Elem * elem);
203 /*!
204 * @brief Function to traverse to the next element in the list (non
205 * atomic)
206 *
207 * @param handle Pointer to the list
208 * @param elem Pointer to the current element
209 *
210 * @retval NULL Operation failed
211 * @retval Valid-pointer Pointer to next element
212 *
213 * @sa List_prev
214 */
215 Ptr List_next (List_Handle handle, List_Elem * elem);
217 /*!
218 * @brief Function to traverse to the previous element in the list (non
219 * atomic)
220 *
221 * @param handle Pointer to the list
222 * @param elem Pointer to the current element
223 *
224 * @retval NULL Operation failed
225 * @retval Valid-pointer Pointer to previous element
226 *
227 * @sa List_next
228 */
229 Ptr List_prev (List_Handle handle, List_Elem * elem);
231 /*!
232 * @brief Function to insert element before the existing element
233 * in the list.
234 *
235 * @param handle Pointer to the list
236 * @param newElem Element to be inserted
237 * @param curElem Existing element before which new one is to be inserted
238 *
239 * @sa List_remove
240 */
241 Void List_insert (List_Handle handle, List_Elem * newElem, List_Elem * curElem);
243 /*!
244 * @brief Function to removes element from the List.
245 *
246 * @param handle Pointer to the list
247 * @param elem Element to be removed
248 *
249 * @sa List_insert
250 */
251 Void List_remove (List_Handle handle, List_Elem * elem);
253 /*!
254 * @brief Function to put the element before head.
255 *
256 * @param handle Pointer to the list
257 * @param elem Element to be added at the head
258 *
259 * @sa List_put
260 */
261 Void List_putHead (List_Handle handle, List_Elem * elem);
263 /*!
264 * @brief Get element from front of List (non-atomic)
265 *
266 * @param handle Pointer to the list
267 *
268 * @retval NULL Operation failed
269 * @retval Valid-pointer Pointer to removed element
270 *
271 * @sa List_enqueue, List_enqueueHead
272 */
273 Ptr List_dequeue (List_Handle handle);
275 /*!
276 * @brief Put element at end of List (non-atomic)
277 *
278 * @param handle Pointer to the list
279 * @param elem Element to be put
280 *
281 * @sa List_dequeue
282 */
283 Void List_enqueue (List_Handle handle, List_Elem * elem);
285 /*!
286 * @brief Put element at head of List (non-atomic)
287 *
288 * @param handle Pointer to the list
289 * @param elem Element to be added
290 *
291 * @sa List_dequeue
292 */
293 Void List_enqueueHead (List_Handle handle, List_Elem * elem);
296 #if defined (__cplusplus)
297 }
298 #endif /* defined (__cplusplus) */
301 #endif /* LIST_H_0XB734 */