Pratyush Mallick / Mbed OS testing

this is testing

app/noos_mbed/include/list.h@0:3afcd581558d, 2021-01-14 (annotated)

Committer:
pmallick
Date:
Thu Jan 14 18:54:16 2021 +0530
Revision:
0:3afcd581558d
this is testing

Who changed what in which revision?

UserRevisionLine numberNew contents of line
pmallick 0:3afcd581558d 1 /***************************************************************************//**
pmallick 0:3afcd581558d 2 * @file list.h
pmallick 0:3afcd581558d 3 * @brief List library header
pmallick 0:3afcd581558d 4 * @author Mihail Chindris (mihail.chindris@analog.com)
pmallick 0:3afcd581558d 5 ********************************************************************************
pmallick 0:3afcd581558d 6 * @copyright
pmallick 0:3afcd581558d 7 * Copyright 2020(c) Analog Devices, Inc.
pmallick 0:3afcd581558d 8 *
pmallick 0:3afcd581558d 9 * All rights reserved.
pmallick 0:3afcd581558d 10 *
pmallick 0:3afcd581558d 11 * Redistribution and use in source and binary forms, with or without
pmallick 0:3afcd581558d 12 * modification, are permitted provided that the following conditions are met:
pmallick 0:3afcd581558d 13 * - Redistributions of source code must retain the above copyright
pmallick 0:3afcd581558d 14 * notice, this list of conditions and the following disclaimer.
pmallick 0:3afcd581558d 15 * - Redistributions in binary form must reproduce the above copyright
pmallick 0:3afcd581558d 16 * notice, this list of conditions and the following disclaimer in
pmallick 0:3afcd581558d 17 * the documentation and/or other materials provided with the
pmallick 0:3afcd581558d 18 * distribution.
pmallick 0:3afcd581558d 19 * - Neither the name of Analog Devices, Inc. nor the names of its
pmallick 0:3afcd581558d 20 * contributors may be used to endorse or promote products derived
pmallick 0:3afcd581558d 21 * from this software without specific prior written permission.
pmallick 0:3afcd581558d 22 * - The use of this software may or may not infringe the patent rights
pmallick 0:3afcd581558d 23 * of one or more patent holders. This license does not release you
pmallick 0:3afcd581558d 24 * from the requirement that you obtain separate licenses from these
pmallick 0:3afcd581558d 25 * patent holders to use this software.
pmallick 0:3afcd581558d 26 * - Use of the software either in source or binary form, must be run
pmallick 0:3afcd581558d 27 * on or directly connected to an Analog Devices Inc. component.
pmallick 0:3afcd581558d 28 *
pmallick 0:3afcd581558d 29 * THIS SOFTWARE IS PROVIDED BY ANALOG DEVICES "AS IS" AND ANY EXPRESS OR
pmallick 0:3afcd581558d 30 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, NON-INFRINGEMENT,
pmallick 0:3afcd581558d 31 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
pmallick 0:3afcd581558d 32 * IN NO EVENT SHALL ANALOG DEVICES BE LIABLE FOR ANY DIRECT, INDIRECT,
pmallick 0:3afcd581558d 33 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
pmallick 0:3afcd581558d 34 * LIMITED TO, INTELLECTUAL PROPERTY RIGHTS, PROCUREMENT OF SUBSTITUTE GOODS OR
pmallick 0:3afcd581558d 35 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
pmallick 0:3afcd581558d 36 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
pmallick 0:3afcd581558d 37 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
pmallick 0:3afcd581558d 38 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
pmallick 0:3afcd581558d 39 ********************************************************************************
pmallick 0:3afcd581558d 40 *
pmallick 0:3afcd581558d 41 * @section list_details Library description
pmallick 0:3afcd581558d 42 * This library handles double linked lists and it expose inseart,
pmallick 0:3afcd581558d 43 * read, get and delete functions. \n
pmallick 0:3afcd581558d 44 * It also can be accesed using it member functions which wrapp function for
pmallick 0:3afcd581558d 45 * usual list types.\n
pmallick 0:3afcd581558d 46 * @subsection example Sample code
pmallick 0:3afcd581558d 47 * @code{.c}
pmallick 0:3afcd581558d 48 * // -- Use a generic list
pmallick 0:3afcd581558d 49 * struct list_desc *list1;
pmallick 0:3afcd581558d 50 * struct iterator *it;
pmallick 0:3afcd581558d 51 * uint32_t a;
pmallick 0:3afcd581558d 52 * // Create list list1
pmallick 0:3afcd581558d 53 * list_init(&list1, LIST_DEFAULT, NULL);
pmallick 0:3afcd581558d 54 * // Add items to the list
pmallick 0:3afcd581558d 55 * list_add_last(list1, 1);
pmallick 0:3afcd581558d 56 * list_add_last(list1, 2);
pmallick 0:3afcd581558d 57 * list_add_last(list1, 3);
pmallick 0:3afcd581558d 58 * // Here the list will be: 1 -> 2 - > 3
pmallick 0:3afcd581558d 59 *
pmallick 0:3afcd581558d 60 * list_read_last(list1, &a);
pmallick 0:3afcd581558d 61 * printf("Last: %d\n", a);
pmallick 0:3afcd581558d 62 * // 3 will be printed
pmallick 0:3afcd581558d 63 * // Create an iterator on the end of the list
pmallick 0:3afcd581558d 64 * iterator_init(&it, list1, 0);
pmallick 0:3afcd581558d 65 * // Move the iterator backword with one position
pmallick 0:3afcd581558d 66 * iterator_move(it, -1);
pmallick 0:3afcd581558d 67 * // Read the data at the current position
pmallick 0:3afcd581558d 68 * iterator_read(it, &a);
pmallick 0:3afcd581558d 69 * printf("Current: %d\n", a);
pmallick 0:3afcd581558d 70 * // 2 will be printed
pmallick 0:3afcd581558d 71 * iterator_remove(it);
pmallick 0:3afcd581558d 72 * list_remove(list1);
pmallick 0:3afcd581558d 73 *
pmallick 0:3afcd581558d 74 * // -- Use a popular list
pmallick 0:3afcd581558d 75 * struct list_desc *stack;
pmallick 0:3afcd581558d 76 * // Create a FIFO list
pmallick 0:3afcd581558d 77 * list_init(&stack, LIST_STACK, NULL);
pmallick 0:3afcd581558d 78 * // Put elements in the list
pmallick 0:3afcd581558d 79 * stack->push(stack, 1);
pmallick 0:3afcd581558d 80 * stack->push(stack, 2);
pmallick 0:3afcd581558d 81 * stack->push(stack, 3);
pmallick 0:3afcd581558d 82 * // Read from the stack
pmallick 0:3afcd581558d 83 * stack->pop(stack, &a);
pmallick 0:3afcd581558d 84 * printf("Last: %d\n", a);
pmallick 0:3afcd581558d 85 * // 3 will be printed
pmallick 0:3afcd581558d 86 * list_remove(stack);
pmallick 0:3afcd581558d 87 * @endcode
pmallick 0:3afcd581558d 88 *******************************************************************************/
pmallick 0:3afcd581558d 89
pmallick 0:3afcd581558d 90 #ifndef LIST_H
pmallick 0:3afcd581558d 91 #define LIST_H
pmallick 0:3afcd581558d 92
pmallick 0:3afcd581558d 93 /******************************************************************************/
pmallick 0:3afcd581558d 94 /***************************** Include Files **********************************/
pmallick 0:3afcd581558d 95 /******************************************************************************/
pmallick 0:3afcd581558d 96
pmallick 0:3afcd581558d 97 #include <stdint.h>
pmallick 0:3afcd581558d 98 #include <stdbool.h>
pmallick 0:3afcd581558d 99
pmallick 0:3afcd581558d 100 /******************************************************************************/
pmallick 0:3afcd581558d 101 /*************************** Types Declarations *******************************/
pmallick 0:3afcd581558d 102 /******************************************************************************/
pmallick 0:3afcd581558d 103
pmallick 0:3afcd581558d 104 /**
pmallick 0:3afcd581558d 105 * @struct list_desc
pmallick 0:3afcd581558d 106 * @brief Structure storing the list and function wrapper for usual list types
pmallick 0:3afcd581558d 107 *
pmallick 0:3afcd581558d 108 * With this structure the funtionalities of usual list types
pmallick 0:3afcd581558d 109 * ( \ref adapter_type ) can be accesed with the functions referenced in this
pmallick 0:3afcd581558d 110 * structure.
pmallick 0:3afcd581558d 111 * For example:
pmallick 0:3afcd581558d 112 * @code{.c}
pmallick 0:3afcd581558d 113 * my_queue->push(my_queue, my_data);
pmallick 0:3afcd581558d 114 * @endcode
pmallick 0:3afcd581558d 115 */
pmallick 0:3afcd581558d 116 struct list_desc;
pmallick 0:3afcd581558d 117
pmallick 0:3afcd581558d 118 /**
pmallick 0:3afcd581558d 119 * @struct list_iterator
pmallick 0:3afcd581558d 120 * @brief Structure used to iterate through the list using Iterator functions.
pmallick 0:3afcd581558d 121 */
pmallick 0:3afcd581558d 122 struct iterator;
pmallick 0:3afcd581558d 123
pmallick 0:3afcd581558d 124 /**
pmallick 0:3afcd581558d 125 * @brief Prototype of the compare function.
pmallick 0:3afcd581558d 126 *
pmallick 0:3afcd581558d 127 * The function used to compare the elements of the liste when doing
pmallick 0:3afcd581558d 128 * operations on an ordered list.
pmallick 0:3afcd581558d 129 * @param data1 - First element to be compared
pmallick 0:3afcd581558d 130 * @param data2 - Second element to be compared
pmallick 0:3afcd581558d 131 * @return
pmallick 0:3afcd581558d 132 * - -1 - If data1 < data2
pmallick 0:3afcd581558d 133 * - 0 - If data1 == data2
pmallick 0:3afcd581558d 134 * - 1 - If data1 > data2
pmallick 0:3afcd581558d 135 */
pmallick 0:3afcd581558d 136 typedef int32_t (*f_cmp)(void *data1, void *data2);
pmallick 0:3afcd581558d 137
pmallick 0:3afcd581558d 138 /**
pmallick 0:3afcd581558d 139 * @name Generic functions
pmallick 0:3afcd581558d 140 * Each function interacting with the list have one of the following formats.\n
pmallick 0:3afcd581558d 141 * Aditionaly they may have one more parametere for specific functionalities.\n
pmallick 0:3afcd581558d 142 * In the Iterator functions, the list reference is replaced by the iterator's
pmallick 0:3afcd581558d 143 * one.
pmallick 0:3afcd581558d 144 * @{
pmallick 0:3afcd581558d 145 */
pmallick 0:3afcd581558d 146
pmallick 0:3afcd581558d 147 /**
pmallick 0:3afcd581558d 148 * @brief Add an element in the list.
pmallick 0:3afcd581558d 149 *
pmallick 0:3afcd581558d 150 * The element of the list is created and the data field is stored in it.
pmallick 0:3afcd581558d 151 * @param list_desc - Reference to the list. Created by \ref list_init
pmallick 0:3afcd581558d 152 * @param data - Data to store in a list element
pmallick 0:3afcd581558d 153 * @return
pmallick 0:3afcd581558d 154 * - \ref SUCCESS : On success
pmallick 0:3afcd581558d 155 * - \ref FAILURE : Otherwise
pmallick 0:3afcd581558d 156 */
pmallick 0:3afcd581558d 157 typedef int32_t (*f_add)(struct list_desc *list_desc, void *data);
pmallick 0:3afcd581558d 158
pmallick 0:3afcd581558d 159 /**
pmallick 0:3afcd581558d 160 * @brief Edit an element in the list. The content is replaced by new_data.
pmallick 0:3afcd581558d 161 * @param list_desc - Reference to the list. Created by \ref list_init .
pmallick 0:3afcd581558d 162 * @param new_data - New data to replace the old one
pmallick 0:3afcd581558d 163 * @return
pmallick 0:3afcd581558d 164 * - \ref SUCCESS : On success
pmallick 0:3afcd581558d 165 * - \ref FAILURE : Otherwise
pmallick 0:3afcd581558d 166 */
pmallick 0:3afcd581558d 167 typedef int32_t (*f_edit)(struct list_desc *list_desc, void *new_data);
pmallick 0:3afcd581558d 168
pmallick 0:3afcd581558d 169 /**
pmallick 0:3afcd581558d 170 * @brief Read an element from the list.
pmallick 0:3afcd581558d 171 * @param list_desc - Reference to the list. Created by \ref list_init
pmallick 0:3afcd581558d 172 * @param result - If not null, result is filled with:
pmallick 0:3afcd581558d 173 * @param data - Content of the list element, NULL if some error occur.
pmallick 0:3afcd581558d 174 * @return \n
pmallick 0:3afcd581558d 175 * - \ref SUCCESS : On success
pmallick 0:3afcd581558d 176 * - \ref FAILURE : Otherwise
pmallick 0:3afcd581558d 177 * @note If the content of an element can be 0 then the result must be checked
pmallick 0:3afcd581558d 178 * to see if the functions has succeded
pmallick 0:3afcd581558d 179 */
pmallick 0:3afcd581558d 180 typedef int32_t (*f_read)(struct list_desc *list_desc, void **data);
pmallick 0:3afcd581558d 181
pmallick 0:3afcd581558d 182 /**
pmallick 0:3afcd581558d 183 * @brief Read and remove an element from the list.
pmallick 0:3afcd581558d 184 * @param list_desc - Reference to the list. Created by \ref list_init
pmallick 0:3afcd581558d 185 * @param result - If not null, result is filled with:
pmallick 0:3afcd581558d 186 * @param data - Content of the list element, NULL if some error occur.
pmallick 0:3afcd581558d 187 * @return
pmallick 0:3afcd581558d 188 * - \ref SUCCESS : On success
pmallick 0:3afcd581558d 189 * - \ref FAILURE : Otherwise
pmallick 0:3afcd581558d 190 */
pmallick 0:3afcd581558d 191 typedef int32_t (*f_get)(struct list_desc *list_desc, void **data);
pmallick 0:3afcd581558d 192
pmallick 0:3afcd581558d 193 /** @} */
pmallick 0:3afcd581558d 194
pmallick 0:3afcd581558d 195 /**
pmallick 0:3afcd581558d 196 * @enum adapter_type
pmallick 0:3afcd581558d 197 * @brief Selects functionalities for functions in \ref list_desc
pmallick 0:3afcd581558d 198 */
pmallick 0:3afcd581558d 199 enum adapter_type {
pmallick 0:3afcd581558d 200 /** Default type is LIST_STACK */
pmallick 0:3afcd581558d 201 LIST_DEFAULT,
pmallick 0:3afcd581558d 202 /**
pmallick 0:3afcd581558d 203 * Functions for a FIFO list (First-in first-out). Elements are inserted
pmallick 0:3afcd581558d 204 * in one end and extracted from the other end.
pmallick 0:3afcd581558d 205 * - \e Push: Insert element
pmallick 0:3afcd581558d 206 * - \e Pop: Get next element (Read and remove)
pmallick 0:3afcd581558d 207 * - \e Top_next: Read next element
pmallick 0:3afcd581558d 208 * - \e Back: Read first element
pmallick 0:3afcd581558d 209 * - \e Swap: Edit the content of the next element
pmallick 0:3afcd581558d 210 */
pmallick 0:3afcd581558d 211 LIST_QUEUE,
pmallick 0:3afcd581558d 212 /**
pmallick 0:3afcd581558d 213 * Functions for a LIFO list (Last-in first-out). Elements are inserted
pmallick 0:3afcd581558d 214 * and extracted only from the same end.
pmallick 0:3afcd581558d 215 * - \e Push: Insert element
pmallick 0:3afcd581558d 216 * - \e Pop: Get top element (Read and remove)
pmallick 0:3afcd581558d 217 * - \e Top_next: Read top element
pmallick 0:3afcd581558d 218 * - \e Back: Read bottom element
pmallick 0:3afcd581558d 219 * - \e Swap: Edit the content of the top element
pmallick 0:3afcd581558d 220 */
pmallick 0:3afcd581558d 221 LIST_STACK,
pmallick 0:3afcd581558d 222 /**
pmallick 0:3afcd581558d 223 * Functions for ordered list. The order of element is determinated
pmallick 0:3afcd581558d 224 * usinge the \ref f_cmp.
pmallick 0:3afcd581558d 225 * - \e Push: Insert element
pmallick 0:3afcd581558d 226 * - \e Pop: Get lowest element (Read and remove)
pmallick 0:3afcd581558d 227 * - \e Top_next: Read lowest element
pmallick 0:3afcd581558d 228 * - \e Back: Read the biggest element
pmallick 0:3afcd581558d 229 * - \e Swap: Edit the lowest element
pmallick 0:3afcd581558d 230 */
pmallick 0:3afcd581558d 231 LIST_PRIORITY_LIST
pmallick 0:3afcd581558d 232 };
pmallick 0:3afcd581558d 233
pmallick 0:3afcd581558d 234 struct list_desc {
pmallick 0:3afcd581558d 235 /** Refer to \ref adapter_type */
pmallick 0:3afcd581558d 236 f_add push;
pmallick 0:3afcd581558d 237 /** Refer to \ref adapter_type */
pmallick 0:3afcd581558d 238 f_get pop;
pmallick 0:3afcd581558d 239 /** Refer to \ref adapter_type */
pmallick 0:3afcd581558d 240 f_read top_next;
pmallick 0:3afcd581558d 241 /** Refer to \ref adapter_type */
pmallick 0:3afcd581558d 242 f_read back;
pmallick 0:3afcd581558d 243 /** Refer to \ref adapter_type */
pmallick 0:3afcd581558d 244 f_edit swap;
pmallick 0:3afcd581558d 245 /** Structure storing the list internal parameters */
pmallick 0:3afcd581558d 246 void *priv_desc;
pmallick 0:3afcd581558d 247 };
pmallick 0:3afcd581558d 248
pmallick 0:3afcd581558d 249 /******************************************************************************/
pmallick 0:3afcd581558d 250 /************************ Functions Declarations ******************************/
pmallick 0:3afcd581558d 251 /******************************************************************************/
pmallick 0:3afcd581558d 252
pmallick 0:3afcd581558d 253 int32_t list_init(struct list_desc **list_desc, enum adapter_type type,
pmallick 0:3afcd581558d 254 f_cmp comparator);
pmallick 0:3afcd581558d 255 int32_t list_remove(struct list_desc *list_desc);
pmallick 0:3afcd581558d 256 int32_t list_get_size(struct list_desc *list_desc, uint32_t *out_size);
pmallick 0:3afcd581558d 257
pmallick 0:3afcd581558d 258 /**
pmallick 0:3afcd581558d 259 * @name Iterator functions
pmallick 0:3afcd581558d 260 * An iterator is used to iterate through the list. For a list, any number of
pmallick 0:3afcd581558d 261 * iterators can be created. All must be removed before removing a list.
pmallick 0:3afcd581558d 262 * @{
pmallick 0:3afcd581558d 263 */
pmallick 0:3afcd581558d 264 int32_t iterator_init(struct iterator **iter, struct list_desc *list_desc,
pmallick 0:3afcd581558d 265 bool start);
pmallick 0:3afcd581558d 266 int32_t iterator_remove(struct iterator *iter);
pmallick 0:3afcd581558d 267 int32_t iterator_move(struct iterator *iter, int32_t idx);
pmallick 0:3afcd581558d 268 int32_t iterator_find(struct iterator *iter, void *cmp_data);
pmallick 0:3afcd581558d 269 int32_t iterator_insert(struct iterator *iter, void *data, bool after);
pmallick 0:3afcd581558d 270 int32_t iterator_edit(struct iterator *iter, void *new_data);
pmallick 0:3afcd581558d 271 int32_t iterator_read(struct iterator *iter, void **data);
pmallick 0:3afcd581558d 272 int32_t iterator_get(struct iterator *iter, void **data);
pmallick 0:3afcd581558d 273 /** @}*/
pmallick 0:3afcd581558d 274
pmallick 0:3afcd581558d 275 /**
pmallick 0:3afcd581558d 276 * @name Operations on the ends of the list
pmallick 0:3afcd581558d 277 * These functions will operate on the first or last element of the list
pmallick 0:3afcd581558d 278 * @{
pmallick 0:3afcd581558d 279 */
pmallick 0:3afcd581558d 280 int32_t list_add_first(struct list_desc *list_desc, void *data);
pmallick 0:3afcd581558d 281 int32_t list_edit_first(struct list_desc *list_desc, void *new_data);
pmallick 0:3afcd581558d 282 int32_t list_read_first(struct list_desc *list_desc, void **data);
pmallick 0:3afcd581558d 283 int32_t list_get_first(struct list_desc *list_desc, void **data);
pmallick 0:3afcd581558d 284
pmallick 0:3afcd581558d 285 int32_t list_add_last(struct list_desc *list_desc, void *data);
pmallick 0:3afcd581558d 286 int32_t list_edit_last(struct list_desc *list_desc, void *new_data);
pmallick 0:3afcd581558d 287 int32_t list_read_last(struct list_desc *list_desc, void **data);
pmallick 0:3afcd581558d 288 int32_t list_get_last(struct list_desc *list_desc, void **data);
pmallick 0:3afcd581558d 289 /** @}*/
pmallick 0:3afcd581558d 290
pmallick 0:3afcd581558d 291 /**
pmallick 0:3afcd581558d 292 * @name Operations by index
pmallick 0:3afcd581558d 293 * These functions use an index to identify the element in the list.
pmallick 0:3afcd581558d 294 * @{
pmallick 0:3afcd581558d 295 */
pmallick 0:3afcd581558d 296 int32_t list_add_idx(struct list_desc *list_desc, void *data, uint32_t idx);
pmallick 0:3afcd581558d 297 int32_t list_edit_idx(struct list_desc *list_desc, void *new_data,
pmallick 0:3afcd581558d 298 uint32_t idx);
pmallick 0:3afcd581558d 299 int32_t list_read_idx(struct list_desc *list_desc, void **data, uint32_t idx);
pmallick 0:3afcd581558d 300 int32_t list_get_idx(struct list_desc *list_desc, void **data, uint32_t idx);
pmallick 0:3afcd581558d 301 /** @}*/
pmallick 0:3afcd581558d 302
pmallick 0:3afcd581558d 303 /**
pmallick 0:3afcd581558d 304 * @name Operations by comparation
pmallick 0:3afcd581558d 305 * These functions use the specified \ref f_cmp at \ref list_init to identify
pmallick 0:3afcd581558d 306 * the element this will operate on.
pmallick 0:3afcd581558d 307 * @{
pmallick 0:3afcd581558d 308 */
pmallick 0:3afcd581558d 309 int32_t list_add_find(struct list_desc *list_desc, void *data);
pmallick 0:3afcd581558d 310 int32_t list_edit_find(struct list_desc *list_desc, void *new_data,
pmallick 0:3afcd581558d 311 void *cmp_data);
pmallick 0:3afcd581558d 312 int32_t list_read_find(struct list_desc *list_desc, void **data,
pmallick 0:3afcd581558d 313 void *cmp_data);
pmallick 0:3afcd581558d 314 int32_t list_get_find(struct list_desc *list_desc, void **data, void *cmp_data);
pmallick 0:3afcd581558d 315 /** @}*/
pmallick 0:3afcd581558d 316
pmallick 0:3afcd581558d 317 #endif //LIST_H