+++ /dev/null
-/*\r
- * Amazon FreeRTOS Common V1.0.0\r
- * Copyright (C) 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.\r
- *\r
- * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
- * this software and associated documentation files (the "Software"), to deal in\r
- * the Software without restriction, including without limitation the rights to\r
- * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
- * the Software, and to permit persons to whom the Software is furnished to do so,\r
- * subject to the following conditions:\r
- *\r
- * The above copyright notice and this permission notice shall be included in all\r
- * copies or substantial portions of the Software.\r
- *\r
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
- * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
- * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
- * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
- * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
- *\r
- * http://aws.amazon.com/freertos\r
- * http://www.FreeRTOS.org\r
- */\r
-\r
-/**\r
- * @file iot_linear_containers.h\r
- * @brief Declares and implements doubly-linked lists and queues.\r
- */\r
-\r
-#ifndef IOT_LINEAR_CONTAINERS_H_\r
-#define IOT_LINEAR_CONTAINERS_H_\r
-\r
-/* The config header is always included first. */\r
-#include "iot_config.h"\r
-\r
-/* Standard includes. */\r
-#include <stdbool.h>\r
-#include <stddef.h>\r
-#include <stdint.h>\r
-\r
-/**\r
- * @defgroup linear_containers_datatypes_listqueue List and queue\r
- * @brief Structures that represent a list or queue.\r
- */\r
-\r
-/**\r
- * @ingroup linear_containers_datatypes_listqueue\r
- * @brief Link member placed in structs of a list or queue.\r
- *\r
- * All elements in a list or queue must contain one of these members. The macro\r
- * #IotLink_Container can be used to calculate the starting address of the\r
- * link's container.\r
- */\r
-typedef struct IotLink\r
-{\r
- struct IotLink * pPrevious; /**< @brief Pointer to the previous element. */\r
- struct IotLink * pNext; /**< @brief Pointer to the next element. */\r
-} IotLink_t;\r
-\r
-/**\r
- * @ingroup linear_containers_datatypes_listqueue\r
- * @brief Represents a doubly-linked list.\r
- */\r
-typedef IotLink_t IotListDouble_t;\r
-\r
-/**\r
- * @ingroup linear_containers_datatypes_listqueue\r
- * @brief Represents a queue.\r
- */\r
-typedef IotLink_t IotDeQueue_t;\r
-\r
-/**\r
- * @constantspage{linear_containers,linear containers library}\r
- *\r
- * @section linear_containers_constants_initializers Linear Containers Initializers\r
- * @brief Provides default values for initializing the linear containers data types.\r
- *\r
- * @snippet this define_linear_containers_initializers\r
- *\r
- * All user-facing data types of the linear containers library should be initialized\r
- * using one of the following.\r
- *\r
- * @warning Failure to initialize a linear containers data type with the appropriate\r
- * initializer may result in a runtime error!\r
- * @note The initializers may change at any time in future versions, but their\r
- * names will remain the same.\r
- */\r
-/* @[define_linear_containers_initializers] */\r
-#define IOT_LINK_INITIALIZER { 0 } /**< @brief Initializer for an #IotLink_t. */\r
-#define IOT_LIST_DOUBLE_INITIALIZER IOT_LINK_INITIALIZER /**< @brief Initializer for an #IotListDouble_t. */\r
-#define IOT_DEQUEUE_INITIALIZER IOT_LINK_INITIALIZER /**< @brief Initializer for an #IotDeQueue_t. */\r
-/* @[define_linear_containers_initializers] */\r
-\r
-/**\r
- * @def IotContainers_Assert( expression )\r
- * @brief Assertion macro for the linear containers library.\r
- *\r
- * Set @ref IOT_CONTAINERS_ENABLE_ASSERTS to `1` to enable assertions in the linear\r
- * containers library.\r
- *\r
- * @param[in] expression Expression to be evaluated.\r
- */\r
-#if IOT_CONTAINERS_ENABLE_ASSERTS == 1\r
- #ifndef IotContainers_Assert\r
- #include <assert.h>\r
- #define IotContainers_Assert( expression ) assert( expression )\r
- #endif\r
-#else\r
- #define IotContainers_Assert( expression )\r
-#endif\r
-\r
-/**\r
- * @brief Calculates the starting address of a containing struct.\r
- *\r
- * @param[in] type Type of the containing struct.\r
- * @param[in] pLink Pointer to a link member.\r
- * @param[in] linkName Name of the #IotLink_t in the containing struct.\r
- */\r
-#define IotLink_Container( type, pLink, linkName ) \\r
- ( ( type * ) ( void * ) ( ( ( uint8_t * ) ( pLink ) ) - offsetof( type, linkName ) ) )\r
-\r
-/**\r
- * @brief Iterates through all elements of a linear container.\r
- *\r
- * Container elements must not be freed or removed while iterating.\r
- *\r
- * @param[in] pStart The first element to iterate from.\r
- * @param[out] pLink Pointer to a container element.\r
- */\r
-#define IotContainers_ForEach( pStart, pLink ) \\r
- for( ( pLink ) = ( pStart )->pNext; \\r
- ( pLink ) != ( pStart ); \\r
- ( pLink ) = ( pLink )->pNext )\r
-\r
-/**\r
- * @functionspage{linear_containers,linear containers library}\r
- * - @functionname{linear_containers_function_link_islinked}\r
- * - @functionname{linear_containers_function_list_double_create}\r
- * - @functionname{linear_containers_function_list_double_count}\r
- * - @functionname{linear_containers_function_list_double_isempty}\r
- * - @functionname{linear_containers_function_list_double_peekhead}\r
- * - @functionname{linear_containers_function_list_double_peektail}\r
- * - @functionname{linear_containers_function_list_double_inserthead}\r
- * - @functionname{linear_containers_function_list_double_inserttail}\r
- * - @functionname{linear_containers_function_list_double_insertbefore}\r
- * - @functionname{linear_containers_function_list_double_insertafter}\r
- * - @functionname{linear_containers_function_list_double_insertsorted}\r
- * - @functionname{linear_containers_function_list_double_remove}\r
- * - @functionname{linear_containers_function_list_double_removehead}\r
- * - @functionname{linear_containers_function_list_double_removetail}\r
- * - @functionname{linear_containers_function_list_double_removeall}\r
- * - @functionname{linear_containers_function_list_double_findfirstmatch}\r
- * - @functionname{linear_containers_function_list_double_removefirstmatch}\r
- * - @functionname{linear_containers_function_list_double_removeallmatches}\r
- * - @functionname{linear_containers_function_queue_create}\r
- * - @functionname{linear_containers_function_queue_count}\r
- * - @functionname{linear_containers_function_queue_isempty}\r
- * - @functionname{linear_containers_function_queue_peekhead}\r
- * - @functionname{linear_containers_function_queue_peektail}\r
- * - @functionname{linear_containers_function_queue_enqueuehead}\r
- * - @functionname{linear_containers_function_queue_dequeuehead}\r
- * - @functionname{linear_containers_function_queue_enqueuetail}\r
- * - @functionname{linear_containers_function_queue_dequeuetail}\r
- * - @functionname{linear_containers_function_queue_remove}\r
- * - @functionname{linear_containers_function_queue_removeall}\r
- * - @functionname{linear_containers_function_queue_removeallmatches}\r
- */\r
-\r
-/**\r
- * @functionpage{IotLink_IsLinked,linear_containers,link_islinked}\r
- * @functionpage{IotListDouble_Create,linear_containers,list_double_create}\r
- * @functionpage{IotListDouble_Count,linear_containers,list_double_count}\r
- * @functionpage{IotListDouble_IsEmpty,linear_containers,list_double_isempty}\r
- * @functionpage{IotListDouble_PeekHead,linear_containers,list_double_peekhead}\r
- * @functionpage{IotListDouble_PeekTail,linear_containers,list_double_peektail}\r
- * @functionpage{IotListDouble_InsertHead,linear_containers,list_double_inserthead}\r
- * @functionpage{IotListDouble_InsertTail,linear_containers,list_double_inserttail}\r
- * @functionpage{IotListDouble_InsertBefore,linear_containers,list_double_insertbefore}\r
- * @functionpage{IotListDouble_InsertAfter,linear_containers,list_double_insertafter}\r
- * @functionpage{IotListDouble_InsertSorted,linear_containers,list_double_insertsorted}\r
- * @functionpage{IotListDouble_Remove,linear_containers,list_double_remove}\r
- * @functionpage{IotListDouble_RemoveHead,linear_containers,list_double_removehead}\r
- * @functionpage{IotListDouble_RemoveTail,linear_containers,list_double_removetail}\r
- * @functionpage{IotListDouble_RemoveAll,linear_containers,list_double_removeall}\r
- * @functionpage{IotListDouble_FindFirstMatch,linear_containers,list_double_findfirstmatch}\r
- * @functionpage{IotListDouble_RemoveFirstMatch,linear_containers,list_double_removefirstmatch}\r
- * @functionpage{IotListDouble_RemoveAllMatches,linear_containers,list_double_removeallmatches}\r
- * @functionpage{IotDeQueue_Create,linear_containers,queue_create}\r
- * @functionpage{IotDeQueue_Count,linear_containers,queue_count}\r
- * @functionpage{IotDeQueue_IsEmpty,linear_containers,queue_isempty}\r
- * @functionpage{IotDeQueue_PeekHead,linear_containers,queue_peekhead}\r
- * @functionpage{IotDeQueue_PeekTail,linear_containers,queue_peektail}\r
- * @functionpage{IotDeQueue_EnqueueHead,linear_containers,queue_enqueuehead}\r
- * @functionpage{IotDeQueue_DequeueHead,linear_containers,queue_dequeuehead}\r
- * @functionpage{IotDeQueue_EnqueueTail,linear_containers,queue_enqueuetail}\r
- * @functionpage{IotDeQueue_DequeueTail,linear_containers,queue_dequeuetail}\r
- * @functionpage{IotDeQueue_Remove,linear_containers,queue_remove}\r
- * @functionpage{IotDeQueue_RemoveAll,linear_containers,queue_removeall}\r
- * @functionpage{IotDeQueue_RemoveAllMatches,linear_containers,queue_removeallmatches}\r
- */\r
-\r
-/**\r
- * @brief Check if an #IotLink_t is linked in a list or queue.\r
- *\r
- * @param[in] pLink The link to check.\r
- *\r
- * @return `true` if `pCurrent` is linked in a list or queue; `false` otherwise.\r
- */\r
-/* @[declare_linear_containers_link_islinked] */\r
-static inline bool IotLink_IsLinked( const IotLink_t * const pLink )\r
-/* @[declare_linear_containers_link_islinked] */\r
-{\r
- bool isLinked = false;\r
-\r
- if( pLink != NULL )\r
- {\r
- isLinked = ( pLink->pNext != NULL ) && ( pLink->pPrevious != NULL );\r
- }\r
-\r
- return isLinked;\r
-}\r
-\r
-/**\r
- * @brief Create a new doubly-linked list.\r
- *\r
- * This function initializes a new doubly-linked list. It must be called on an\r
- * uninitialized #IotListDouble_t before calling any other doubly-linked list\r
- * function. This function must not be called on an already-initialized\r
- * #IotListDouble_t.\r
- *\r
- * This function will not fail. The function @ref linear_containers_function_list_double_removeall\r
- * may be called to destroy a list.\r
- *\r
- * @param[in] pList Pointer to the memory that will hold the new doubly-linked list.\r
- */\r
-/* @[declare_linear_containers_list_double_create] */\r
-static inline void IotListDouble_Create( IotListDouble_t * const pList )\r
-/* @[declare_linear_containers_list_double_create] */\r
-{\r
- /* This function must not be called with a NULL parameter. */\r
- IotContainers_Assert( pList != NULL );\r
-\r
- /* An empty list is a link pointing to itself. */\r
- pList->pPrevious = pList;\r
- pList->pNext = pList;\r
-}\r
-\r
-/**\r
- * @brief Return the number of elements contained in an #IotListDouble_t.\r
- *\r
- * @param[in] pList The doubly-linked list with the elements to count.\r
- *\r
- * @return The number of elements in the doubly-linked list.\r
- */\r
-/* @[declare_linear_containers_list_double_count] */\r
-static inline size_t IotListDouble_Count( const IotListDouble_t * const pList )\r
-/* @[declare_linear_containers_list_double_count] */\r
-{\r
- size_t count = 0;\r
-\r
- if( pList != NULL )\r
- {\r
- /* Get the list head. */\r
- const IotLink_t * pCurrent = pList->pNext;\r
-\r
- /* Iterate through the list to count the elements. */\r
- while( pCurrent != pList )\r
- {\r
- count++;\r
- pCurrent = pCurrent->pNext;\r
- }\r
- }\r
-\r
- return count;\r
-}\r
-\r
-/**\r
- * @brief Check if a doubly-linked list is empty.\r
- *\r
- * @param[in] pList The doubly-linked list to check.\r
- *\r
- * @return `true` if the list is empty; `false` otherwise.\r
- */\r
-/* @[declare_linear_containers_list_double_isempty] */\r
-static inline bool IotListDouble_IsEmpty( const IotListDouble_t * const pList )\r
-/* @[declare_linear_containers_list_double_isempty] */\r
-{\r
- /* An empty list is NULL link, or a link pointing to itself. */\r
- return( ( pList == NULL ) || ( pList->pNext == pList ) );\r
-}\r
-\r
-/**\r
- * @brief Return an #IotLink_t representing the first element in a doubly-linked list\r
- * without removing it.\r
- *\r
- * @param[in] pList The list to peek.\r
- *\r
- * @return Pointer to an #IotLink_t representing the element at the head of the\r
- * list; `NULL` if the list is empty. The macro #IotLink_Container may be used to\r
- * determine the address of the link's container.\r
- */\r
-/* @[declare_linear_containers_list_double_peekhead] */\r
-static inline IotLink_t * IotListDouble_PeekHead( const IotListDouble_t * const pList )\r
-/* @[declare_linear_containers_list_double_peekhead] */\r
-{\r
- IotLink_t * pHead = NULL;\r
-\r
- if( pList != NULL )\r
- {\r
- if( IotListDouble_IsEmpty( pList ) == false )\r
- {\r
- pHead = pList->pNext;\r
- }\r
- }\r
-\r
- return pHead;\r
-}\r
-\r
-/**\r
- * @brief Return an #IotLink_t representing the last element in a doubly-linked\r
- * list without removing it.\r
- *\r
- * @param[in] pList The list to peek.\r
- *\r
- * @return Pointer to an #IotLink_t representing the element at the tail of the\r
- * list; `NULL` if the list is empty. The macro #IotLink_Container may be used to\r
- * determine the address of the link's container.\r
- */\r
-/* @[declare_linear_containers_list_double_peektail] */\r
-static inline IotLink_t * IotListDouble_PeekTail( const IotListDouble_t * const pList )\r
-/* @[declare_linear_containers_list_double_peektail] */\r
-{\r
- IotLink_t * pTail = NULL;\r
-\r
- if( pList != NULL )\r
- {\r
- if( IotListDouble_IsEmpty( pList ) == false )\r
- {\r
- pTail = pList->pPrevious;\r
- }\r
- }\r
-\r
- return pTail;\r
-}\r
-\r
-/**\r
- * @brief Insert an element at the head of a doubly-linked list.\r
- *\r
- * @param[in] pList The doubly-linked list that will hold the new element.\r
- * @param[in] pLink Pointer to the new element's link member.\r
- */\r
-/* @[declare_linear_containers_list_double_inserthead] */\r
-static inline void IotListDouble_InsertHead( IotListDouble_t * const pList,\r
- IotLink_t * const pLink )\r
-/* @[declare_linear_containers_list_double_inserthead] */\r
-{\r
- /* This function must not be called with NULL parameters. */\r
- IotContainers_Assert( pList != NULL );\r
- IotContainers_Assert( pLink != NULL );\r
-\r
- /* Save current list head. */\r
- IotLink_t * pHead = pList->pNext;\r
-\r
- /* Place new element before list head. */\r
- pLink->pNext = pHead;\r
- pLink->pPrevious = pList;\r
-\r
- /* Assign new list head. */\r
- pHead->pPrevious = pLink;\r
- pList->pNext = pLink;\r
-}\r
-\r
-/**\r
- * @brief Insert an element at the tail of a doubly-linked list.\r
- *\r
- * @param[in] pList The double-linked list that will hold the new element.\r
- * @param[in] pLink Pointer to the new element's link member.\r
- */\r
-/* @[declare_linear_containers_list_double_inserttail] */\r
-static inline void IotListDouble_InsertTail( IotListDouble_t * const pList,\r
- IotLink_t * const pLink )\r
-/* @[declare_linear_containers_list_double_inserttail] */\r
-{\r
- /* This function must not be called with NULL parameters. */\r
- IotContainers_Assert( pList != NULL );\r
- IotContainers_Assert( pLink != NULL );\r
-\r
- /* Save current list tail. */\r
- IotLink_t * pTail = pList->pPrevious;\r
-\r
- pLink->pNext = pList;\r
- pLink->pPrevious = pTail;\r
-\r
- pList->pPrevious = pLink;\r
- pTail->pNext = pLink;\r
-}\r
-\r
-/**\r
- * @brief Insert an element before another element in a doubly-linked list.\r
- *\r
- * @param[in] pElement The new element will be placed before this element.\r
- * @param[in] pLink Pointer to the new element's link member.\r
- */\r
-/* @[declare_linear_containers_list_double_insertbefore] */\r
-static inline void IotListDouble_InsertBefore( IotLink_t * const pElement,\r
- IotLink_t * const pLink )\r
-/* @[declare_linear_containers_list_double_insertbefore] */\r
-{\r
- IotListDouble_InsertTail( pElement, pLink );\r
-}\r
-\r
-/**\r
- * @brief Insert an element after another element in a doubly-linked list.\r
- *\r
- * @param[in] pElement The new element will be placed after this element.\r
- * @param[in] pLink Pointer to the new element's link member.\r
- */\r
-/* @[declare_linear_containers_list_double_insertafter] */\r
-static inline void IotListDouble_InsertAfter( IotLink_t * const pElement,\r
- IotLink_t * const pLink )\r
-/* @[declare_linear_containers_list_double_insertafter] */\r
-{\r
- IotListDouble_InsertHead( pElement, pLink );\r
-}\r
-\r
-/**\r
- * @brief Insert an element in a sorted doubly-linked list.\r
- *\r
- * Places an element into a list by sorting it into order. The function\r
- * `compare` is used to determine where to place the new element.\r
- *\r
- * @param[in] pList The list that will hold the new element.\r
- * @param[in] pLink Pointer to the new element's link member.\r
- * @param[in] compare Determines the order of the list. Returns a negative\r
- * value if its first argument is less than its second argument; returns\r
- * zero if its first argument is equal to its second argument; returns a\r
- * positive value if its first argument is greater than its second argument.\r
- * The parameters to this function are #IotLink_t, so the macro #IotLink_Container\r
- * may be used to determine the address of the link's container.\r
- */\r
-/* @[declare_linear_containers_list_double_insertsorted] */\r
-static inline void IotListDouble_InsertSorted( IotListDouble_t * const pList,\r
- IotLink_t * const pLink,\r
- int32_t ( *compare )( const IotLink_t * const, const IotLink_t * const ) )\r
-/* @[declare_linear_containers_list_double_insertsorted] */\r
-{\r
- /* This function must not be called with NULL parameters. */\r
- IotContainers_Assert( pList != NULL );\r
- IotContainers_Assert( pLink != NULL );\r
- IotContainers_Assert( compare != NULL );\r
-\r
- /* Insert at head for empty list. */\r
- if( IotListDouble_IsEmpty( pList ) == true )\r
- {\r
- IotListDouble_InsertHead( pList, pLink );\r
- }\r
- else\r
- {\r
- bool inserted = false;\r
- IotLink_t * pCurrent = pList->pNext;\r
-\r
- /* Iterate through the list to find the correct position. */\r
- while( pCurrent != pList )\r
- {\r
- /* Comparing for '<' preserves the order of insertion. */\r
- if( compare( pLink, pCurrent ) < 0 )\r
- {\r
- IotListDouble_InsertBefore( pCurrent, pLink );\r
- inserted = true;\r
-\r
- break;\r
- }\r
-\r
- pCurrent = pCurrent->pNext;\r
- }\r
-\r
- /* New element is greater than all elements in list. Insert at tail. */\r
- if( inserted == false )\r
- {\r
- IotListDouble_InsertTail( pList, pLink );\r
- }\r
- }\r
-}\r
-\r
-/**\r
- * @brief Remove a single element from a doubly-linked list.\r
- *\r
- * @param[in] pLink The element to remove.\r
- */\r
-/* @[declare_linear_containers_list_double_remove] */\r
-static inline void IotListDouble_Remove( IotLink_t * const pLink )\r
-/* @[declare_linear_containers_list_double_remove] */\r
-{\r
- /* This function must not be called with a NULL parameter. */\r
- IotContainers_Assert( pLink != NULL );\r
-\r
- /* This function must be called on a linked element. */\r
- IotContainers_Assert( IotLink_IsLinked( pLink ) == true );\r
-\r
- pLink->pPrevious->pNext = pLink->pNext;\r
- pLink->pNext->pPrevious = pLink->pPrevious;\r
- pLink->pPrevious = NULL;\r
- pLink->pNext = NULL;\r
-}\r
-\r
-/**\r
- * @brief Remove the element at the head of a doubly-linked list.\r
- *\r
- * @param[in] pList The doubly-linked list that holds the element to remove.\r
- *\r
- * @return Pointer to an #IotLink_t representing the removed list head; `NULL`\r
- * if the list is empty. The macro #IotLink_Container may be used to determine\r
- * the address of the link's container.\r
- */\r
-/* @[declare_linear_containers_list_double_removehead] */\r
-static inline IotLink_t * IotListDouble_RemoveHead( IotListDouble_t * const pList )\r
-/* @[declare_linear_containers_list_double_removehead] */\r
-{\r
- IotLink_t * pHead = NULL;\r
-\r
- if( IotListDouble_IsEmpty( pList ) == false )\r
- {\r
- pHead = pList->pNext;\r
- IotListDouble_Remove( pHead );\r
- }\r
-\r
- return pHead;\r
-}\r
-\r
-/**\r
- * @brief Remove the element at the tail of a doubly-linked list.\r
- *\r
- * @param[in] pList The doubly-linked list that holds the element to remove.\r
- *\r
- * @return Pointer to an #IotLink_t representing the removed list tail; `NULL`\r
- * if the list is empty. The macro #IotLink_Container may be used to determine\r
- * the address of the link's container.\r
- */\r
-/* @[declare_linear_containers_list_double_removetail] */\r
-static inline IotLink_t * IotListDouble_RemoveTail( IotListDouble_t * const pList )\r
-/* @[declare_linear_containers_list_double_removetail] */\r
-{\r
- IotLink_t * pTail = NULL;\r
-\r
- if( IotListDouble_IsEmpty( pList ) == false )\r
- {\r
- pTail = pList->pPrevious;\r
- IotListDouble_Remove( pTail );\r
- }\r
-\r
- return pTail;\r
-}\r
-\r
-/**\r
- * @brief Remove all elements in a doubly-linked list.\r
- *\r
- * @param[in] pList The list to empty.\r
- * @param[in] freeElement A function to free memory used by each removed list\r
- * element. Optional; pass `NULL` to ignore.\r
- * @param[in] linkOffset Offset in bytes of a link member in its container, used\r
- * to calculate the pointer to pass to `freeElement`. This value should be calculated\r
- * with the C `offsetof` macro. This parameter is ignored if `freeElement` is `NULL`\r
- * or its value is `0`.\r
- */\r
-/* @[declare_linear_containers_list_double_removeall] */\r
-static inline void IotListDouble_RemoveAll( IotListDouble_t * const pList,\r
- void ( *freeElement )( void * ),\r
- size_t linkOffset )\r
-/* @[declare_linear_containers_list_double_removeall] */\r
-{\r
- /* This function must not be called with a NULL pList parameter. */\r
- IotContainers_Assert( pList != NULL );\r
-\r
- /* Get the list head. */\r
- IotLink_t * pCurrent = pList->pNext;\r
-\r
- /* Iterate through the list and remove all elements. */\r
- while( pCurrent != pList )\r
- {\r
- /* Save a pointer to the next list element. */\r
- IotLink_t * pNext = pCurrent->pNext;\r
-\r
- /* Remove and free the current list element. */\r
- IotListDouble_Remove( pCurrent );\r
-\r
- if( freeElement != NULL )\r
- {\r
- freeElement( ( ( uint8_t * ) pCurrent ) - linkOffset );\r
- }\r
-\r
- /* Move the iterating pointer to the next list element. */\r
- pCurrent = pNext;\r
- }\r
-}\r
-\r
-/**\r
- * @brief Search a doubly-linked list for the first matching element.\r
- *\r
- * If a match is found, the matching element is <b>not</b> removed from the list.\r
- * See @ref linear_containers_function_list_double_removefirstmatch for the function\r
- * that searches and removes.\r
- *\r
- * @param[in] pList The doubly-linked list to search.\r
- * @param[in] pStartPoint An element in `pList`. Only elements between this one and\r
- * the list tail are checked. Pass `NULL` to search from the beginning of the list.\r
- * @param[in] isMatch Function to determine if an element matches. Pass `NULL` to\r
- * search using the address `pMatch`, i.e. `element == pMatch`.\r
- * @param[in] pMatch If `isMatch` is `NULL`, each element in the list is compared\r
- * to this address to find a match. Otherwise, it is passed as the second argument\r
- * to `isMatch`.\r
- *\r
- * @return Pointer to an #IotLink_t representing the first matched element; `NULL`\r
- * if no match is found. The macro #IotLink_Container may be used to determine the\r
- * address of the link's container.\r
- */\r
-/* @[declare_linear_containers_list_double_findfirstmatch] */\r
-static inline IotLink_t * IotListDouble_FindFirstMatch( const IotListDouble_t * const pList,\r
- const IotLink_t * const pStartPoint,\r
- bool ( *isMatch )( const IotLink_t * const, void * ),\r
- void * pMatch )\r
-/* @[declare_linear_containers_list_double_findfirstmatch] */\r
-{\r
- /* The const must be cast away to match this function's return value. Nevertheless,\r
- * this function will respect the const-ness of pStartPoint. */\r
- IotLink_t * pCurrent = ( IotLink_t * ) pStartPoint;\r
-\r
- /* This function must not be called with a NULL pList parameter. */\r
- IotContainers_Assert( pList != NULL );\r
-\r
- /* Search starting from list head if no start point is given. */\r
- if( pStartPoint == NULL )\r
- {\r
- pCurrent = pList->pNext;\r
- }\r
-\r
- /* Iterate through the list to search for matches. */\r
- while( pCurrent != pList )\r
- {\r
- /* Call isMatch if provided. Otherwise, compare pointers. */\r
- if( isMatch != NULL )\r
- {\r
- if( isMatch( pCurrent, pMatch ) == true )\r
- {\r
- return pCurrent;\r
- }\r
- }\r
- else\r
- {\r
- if( pCurrent == pMatch )\r
- {\r
- return pCurrent;\r
- }\r
- }\r
-\r
- pCurrent = pCurrent->pNext;\r
- }\r
-\r
- /* No match found, return NULL. */\r
- return NULL;\r
-}\r
-\r
-/**\r
- * @brief Search a doubly-linked list for the first matching element and remove\r
- * it.\r
- *\r
- * An #IotLink_t may be passed as `pList` to start searching after the head of a\r
- * doubly-linked list.\r
- *\r
- * @param[in] pList The doubly-linked list to search.\r
- * @param[in] pStartPoint An element in `pList`. Only elements between this one and\r
- * the list tail are checked. Pass `NULL` to search from the beginning of the list.\r
- * @param[in] isMatch Function to determine if an element matches. Pass `NULL` to\r
- * search using the address `pMatch`, i.e. `element == pMatch`.\r
- * @param[in] pMatch If `isMatch` is `NULL`, each element in the list is compared\r
- * to this address to find a match. Otherwise, it is passed as the second argument\r
- * to `isMatch`.\r
- *\r
- * @return Pointer to an #IotLink_t representing the matched and removed element;\r
- * `NULL` if no match is found. The macro #IotLink_Container may be used to determine\r
- * the address of the link's container.\r
- */\r
-/* @[declare_linear_containers_list_double_removefirstmatch] */\r
-static inline IotLink_t * IotListDouble_RemoveFirstMatch( IotListDouble_t * const pList,\r
- const IotLink_t * const pStartPoint,\r
- bool ( *isMatch )( const IotLink_t *, void * ),\r
- void * pMatch )\r
-/* @[declare_linear_containers_list_double_removefirstmatch] */\r
-{\r
- IotLink_t * pMatchedElement = IotListDouble_FindFirstMatch( pList,\r
- pStartPoint,\r
- isMatch,\r
- pMatch );\r
-\r
- if( pMatchedElement != NULL )\r
- {\r
- IotListDouble_Remove( pMatchedElement );\r
- }\r
-\r
- return pMatchedElement;\r
-}\r
-\r
-/**\r
- * @brief Remove all matching elements from a doubly-linked list.\r
- *\r
- * @param[in] pList The doubly-linked list to search.\r
- * @param[in] isMatch Function to determine if an element matches. Pass `NULL` to\r
- * search using the address `pMatch`, i.e. `element == pMatch`.\r
- * @param[in] pMatch If `isMatch` is `NULL`, each element in the list is compared\r
- * to this address to find a match. Otherwise, it is passed as the second argument\r
- * to `isMatch`.\r
- * @param[in] freeElement A function to free memory used by each removed list\r
- * element. Optional; pass `NULL` to ignore.\r
- * @param[in] linkOffset Offset in bytes of a link member in its container, used\r
- * to calculate the pointer to pass to `freeElement`. This value should be calculated\r
- * with the C `offsetof` macro. This parameter is ignored if `freeElement` is `NULL`\r
- * or its value is `0`.\r
- */\r
-/* @[declare_linear_containers_list_double_removeallmatches] */\r
-static inline void IotListDouble_RemoveAllMatches( IotListDouble_t * const pList,\r
- bool ( *isMatch )( const IotLink_t *, void * ),\r
- void * pMatch,\r
- void ( *freeElement )( void * ),\r
- size_t linkOffset )\r
-/* @[declare_linear_containers_list_double_removeallmatches] */\r
-{\r
- IotLink_t * pMatchedElement = NULL, * pNextElement = NULL;\r
-\r
- /* Search the list for all matching elements. */\r
- do\r
- {\r
- pMatchedElement = IotListDouble_FindFirstMatch( pList,\r
- pMatchedElement,\r
- isMatch,\r
- pMatch );\r
-\r
- if( pMatchedElement != NULL )\r
- {\r
- /* Save pointer to next element. */\r
- pNextElement = pMatchedElement->pNext;\r
-\r
- /* Match found; remove and free. */\r
- IotListDouble_Remove( pMatchedElement );\r
-\r
- if( freeElement != NULL )\r
- {\r
- freeElement( ( ( uint8_t * ) pMatchedElement ) - linkOffset );\r
- }\r
-\r
- /* Continue search from next element. */\r
- pMatchedElement = pNextElement;\r
- }\r
- } while( pMatchedElement != NULL );\r
-}\r
-\r
-/**\r
- * @brief Create a new queue.\r
- *\r
- * This function initializes a new double-ended queue. It must be called on an uninitialized\r
- * #IotDeQueue_t before calling any other queue function. This function must not be\r
- * called on an already-initialized #IotDeQueue_t.\r
- *\r
- * This function will not fail.\r
- *\r
- * @param[in] pQueue Pointer to the memory that will hold the new queue.\r
- */\r
-/* @[declare_linear_containers_queue_create] */\r
-static inline void IotDeQueue_Create( IotDeQueue_t * const pQueue )\r
-/* @[declare_linear_containers_queue_create] */\r
-{\r
- IotListDouble_Create( pQueue );\r
-}\r
-\r
-/**\r
- * @brief Return the number of elements contained in an #IotDeQueue_t.\r
- *\r
- * @param[in] pQueue The queue with the elements to count.\r
- *\r
- * @return The number of items elements in the queue.\r
- */\r
-/* @[declare_linear_containers_queue_count] */\r
-static inline size_t IotDeQueue_Count( const IotDeQueue_t * const pQueue )\r
-/* @[declare_linear_containers_queue_count] */\r
-{\r
- return IotListDouble_Count( pQueue );\r
-}\r
-\r
-/**\r
- * @brief Check if a queue is empty.\r
- *\r
- * @param[in] pQueue The queue to check.\r
- *\r
- * @return `true` if the queue is empty; `false` otherwise.\r
- *\r
- */\r
-/* @[declare_linear_containers_queue_isempty] */\r
-static inline bool IotDeQueue_IsEmpty( const IotDeQueue_t * const pQueue )\r
-/* @[declare_linear_containers_queue_isempty] */\r
-{\r
- return IotListDouble_IsEmpty( pQueue );\r
-}\r
-\r
-/**\r
- * @brief Return an #IotLink_t representing the element at the front of the queue\r
- * without removing it.\r
- *\r
- * @param[in] pQueue The queue to peek.\r
- *\r
- * @return Pointer to an #IotLink_t representing the element at the head of the\r
- * queue; `NULL` if the queue is empty. The macro #IotLink_Container may be used\r
- * to determine the address of the link's container.\r
- */\r
-/* @[declare_linear_containers_queue_peekhead] */\r
-static inline IotLink_t * IotDeQueue_PeekHead( const IotDeQueue_t * const pQueue )\r
-/* @[declare_linear_containers_queue_peekhead] */\r
-{\r
- return IotListDouble_PeekHead( pQueue );\r
-}\r
-\r
-/**\r
- * @brief Return an #IotLink_t representing the element at the back of the queue\r
- * without removing it.\r
- *\r
- * @param[in] pQueue The queue to peek.\r
- *\r
- * @return Pointer to an #IotLink_t representing the element at the head of the\r
- * queue; `NULL` if the queue is empty. The macro #IotLink_Container may be used\r
- * to determine the address of the link's container.\r
- */\r
-/* @[declare_linear_containers_queue_peektail] */\r
-static inline IotLink_t * IotDeQueue_PeekTail( const IotDeQueue_t * const pQueue )\r
-/* @[declare_linear_containers_queue_peektail] */\r
-{\r
- return IotListDouble_PeekTail( pQueue );\r
-}\r
-\r
-/**\r
- * @brief Add an element at the head of the queue.\r
- *\r
- * @param[in] pQueue The queue that will hold the new element.\r
- * @param[in] pLink Pointer to the new element's link member.\r
- */\r
-/* @[declare_linear_containers_queue_enqueuehead] */\r
-static inline void IotDeQueue_EnqueueHead( IotDeQueue_t * const pQueue,\r
- IotLink_t * const pLink )\r
-/* @[declare_linear_containers_queue_enqueuehead] */\r
-{\r
- IotListDouble_InsertHead( pQueue, pLink );\r
-}\r
-\r
-/**\r
- * @brief Remove an element at the head of the queue.\r
- *\r
- * @param[in] pQueue The queue that holds the element to remove.\r
- *\r
- * @return Pointer to an #IotLink_t representing the removed queue element; `NULL`\r
- * if the queue is empty. The macro #IotLink_Container may be used to determine\r
- * the address of the link's container.\r
- */\r
-/* @[declare_linear_containers_queue_dequeuehead] */\r
-static inline IotLink_t * IotDeQueue_DequeueHead( IotDeQueue_t * const pQueue )\r
-/* @[declare_linear_containers_queue_dequeuehead] */\r
-{\r
- return IotListDouble_RemoveHead( pQueue );\r
-}\r
-\r
-/**\r
- * @brief Add an element at the tail of the queue.\r
- *\r
- * @param[in] pQueue The queue that will hold the new element.\r
- * @param[in] pLink Pointer to the new element's link member.\r
- */\r
-/* @[declare_linear_containers_queue_enqueuetail] */\r
-static inline void IotDeQueue_EnqueueTail( IotDeQueue_t * const pQueue,\r
- IotLink_t * const pLink )\r
-/* @[declare_linear_containers_queue_enqueuetail] */\r
-{\r
- IotListDouble_InsertTail( pQueue, pLink );\r
-}\r
-\r
-/**\r
- * @brief Remove an element at the tail of the queue.\r
- *\r
- * @param[in] pQueue The queue that holds the element to remove.\r
- *\r
- * @return Pointer to an #IotLink_t representing the removed queue element; `NULL`\r
- * if the queue is empty. The macro #IotLink_Container may be used to determine\r
- * the address of the link's container.\r
- */\r
-/* @[declare_linear_containers_queue_dequeuetail] */\r
-static inline IotLink_t * IotDeQueue_DequeueTail( IotDeQueue_t * const pQueue )\r
-/* @[declare_linear_containers_queue_dequeuetail] */\r
-{\r
- return IotListDouble_RemoveTail( pQueue );\r
-}\r
-\r
-/**\r
- * @brief Remove a single element from a queue.\r
- *\r
- * @param[in] pLink The element to remove.\r
- */\r
-/* @[declare_linear_containers_queue_remove] */\r
-static inline void IotDeQueue_Remove( IotLink_t * const pLink )\r
-/* @[declare_linear_containers_queue_remove] */\r
-{\r
- IotListDouble_Remove( pLink );\r
-}\r
-\r
-/**\r
- * @brief Remove all elements in a queue.\r
- *\r
- * @param[in] pQueue The queue to empty.\r
- * @param[in] freeElement A function to free memory used by each removed queue\r
- * element. Optional; pass `NULL` to ignore.\r
- * @param[in] linkOffset Offset in bytes of a link member in its container, used\r
- * to calculate the pointer to pass to `freeElement`. This value should be calculated\r
- * with the C `offsetof` macro. This parameter is ignored if `freeElement` is `NULL`\r
- * or its value is `0`.\r
- */\r
-/* @[declare_linear_containers_queue_removeall] */\r
-static inline void IotDeQueue_RemoveAll( IotDeQueue_t * const pQueue,\r
- void ( * freeElement )( void * ),\r
- size_t linkOffset )\r
-/* @[declare_linear_containers_queue_removeall] */\r
-{\r
- IotListDouble_RemoveAll( pQueue, freeElement, linkOffset );\r
-}\r
-\r
-/**\r
- * @brief Remove all matching elements from a queue.\r
- *\r
- * @param[in] pQueue The queue to search.\r
- * @param[in] isMatch Function to determine if an element matches. Pass `NULL` to\r
- * search using the address `pMatch`, i.e. `element == pMatch`.\r
- * @param[in] pMatch If `isMatch` is `NULL`, each element in the queue is compared\r
- * to this address to find a match. Otherwise, it is passed as the second argument\r
- * to `isMatch`.\r
- * @param[in] freeElement A function to free memory used by each removed queue\r
- * element. Optional; pass `NULL` to ignore.\r
- * @param[in] linkOffset Offset in bytes of a link member in its container, used\r
- * to calculate the pointer to pass to `freeElement`. This value should be calculated\r
- * with the C `offsetof` macro. This parameter is ignored if `freeElement` is `NULL`\r
- * or its value is `0`.\r
- */\r
-/* @[declare_linear_containers_queue_removeallmatches] */\r
-static inline void IotDeQueue_RemoveAllMatches( IotDeQueue_t * const pQueue,\r
- bool ( * isMatch )( const IotLink_t *, void * ),\r
- void * pMatch,\r
- void ( * freeElement )( void * ),\r
- size_t linkOffset )\r
-/* @[declare_linear_containers_queue_removeallmatches] */\r
-{\r
- IotListDouble_RemoveAllMatches( pQueue, isMatch, pMatch, freeElement, linkOffset );\r
-}\r
-\r
-#endif /* IOT_LINEAR_CONTAINERS_H_ */\r
projects / freertos / blobdiff