Singly-Linked List
Singly-Linked List. More...
Modules |
|
Types | |
Singly-Linked List data types.
|
|
Macros | |
Singly-Linked List data macros.
|
|
Detailed Description
Singly-Linked List.
A singly-linked list, is a list of entries where each entry 'points' to the next entry.
- Note
- The memory used by a list entry MUST persist while the entry is in the list.
The following defines a generic list entry:
An actual implementation may define the entry struct as required by the application. The only requirement by this library is that the
next
field MUST be the FIRST member in the entry struct.
i.e. An application can define the 'entry' struct however it needs, but the first member of the struct must be a pointer that is used by this library to create the linked list.
For example: An application's 'entry' struct could look like:
The
next
field is required to be the first member in struct. However, anything may come after
next
.
Function Documentation
◆ gos_safe_slinked_list_add_at_index()
gos_result_t gos_safe_slinked_list_add_at_index | ( | gos_safe_slinked_list_t * |
list,
|
uint32_t |
index,
|
||
void * |
entry
|
||
) |
Add an entry at a specific index
This adds an entry at a specific index of the list.
Optionally use GOS_SAFE_SLINKED_LIST_FIRST to add to the head of the list or GOS_SAFE_SLINKED_LIST_LAST to add to the tail of the list.
- Parameters
-
[in] list
Thread-safe, singly-linked list [in] index
Index to insert entry into list [in] entry
Entry to add to list
- Returns
- gos_result_t , result of API
◆ gos_safe_slinked_list_find_by()
gos_result_t gos_safe_slinked_list_find_by | ( | gos_safe_slinked_list_t * |
list,
|
gos_safe_slinked_list_callback_t |
callback,
|
||
void * |
user,
|
||
void ** |
entry_ptr
|
||
) |
Find list entry by callback
This iterates each entry in the list and invokes the given
callback
. If the
gos_safe_slinked_list_callback_t
returns
true
then the entry IS found. If the
gos_safe_slinked_list_callback_t
returns
false
then the search continues.
- Note
-
The
callback
is invoked atomically and MUST NOT block!
- Parameters
-
[in] list
Thread-safe, singly-linked list [in] callback
Callback to be invoked to determine if the entry is found [in] user
User argument provided to callback [out] entry_ptr
Pointer to hold found entry
- Returns
- gos_result_t , result of API
◆ gos_safe_slinked_list_flush()
void gos_safe_slinked_list_flush | ( | gos_safe_slinked_list_t * |
list,
|
gos_safe_slinked_list_callback_t |
callback,
|
||
void * |
user
|
||
) |
Remove all entries in list
This iterates through each entry in the list and invokes the given
callback
. Typically, the callback is used to de-allocate any memory used by the list entry.
After iterating the list, all entries are removed from the list.
- Note
- The callback is NOT called atomically
- Parameters
-
[in] list
Thread-safe, singly-linked list [in] callback
Callback to be invoked for each entry in the list [in] user
User argument provided to callback
◆ gos_safe_slinked_list_get_count()
uint16_t gos_safe_slinked_list_get_count | ( | const gos_safe_slinked_list_t * |
list
|
) |
Return list entry count
- Parameters
-
[in] list
Thread-safe, singly-linked list
- Returns
- Number of entries in list
◆ gos_safe_slinked_list_get_free_space_count()
uint16_t gos_safe_slinked_list_get_free_space_count | ( | const gos_safe_slinked_list_t * |
list
|
) |
Return number of empty slots in list
- Parameters
-
[in] list
Thread-safe, singly-linked list
- Returns
- Number of empty slots in list
◆ gos_safe_slinked_list_init()
gos_result_t gos_safe_slinked_list_init | ( | gos_safe_slinked_list_t * |
list,
|
uint16_t |
max_count
|
||
) |
Initialize thread-safe singly-linked list
This initializes a thread-safe singly-linked list.
- Parameters
-
[in] list
List to initialize [in] max_count
Maximum entries list may hold, use GOS_SAFE_SLINKED_LIST_UNLIMITED for unlimited size
- Returns
- gos_result_t , result of API
◆ gos_safe_slinked_list_is_empty()
bool gos_safe_slinked_list_is_empty | ( | const gos_safe_slinked_list_t * |
list
|
) |
Return if list is empty
- Parameters
-
[in] list
Thread-safe, singly-linked list
- Returns
- true if list is empty, false else
◆ gos_safe_slinked_list_is_full()
bool gos_safe_slinked_list_is_full | ( | const gos_safe_slinked_list_t * |
list
|
) |
Return if list is fully
- Parameters
-
[in] list
Thread-safe, singly-linked list
- Returns
- true if list if full, false else
◆ gos_safe_slinked_list_pop()
gos_result_t gos_safe_slinked_list_pop | ( | gos_safe_slinked_list_t * |
list,
|
void ** |
entry_ptr
|
||
) |
Remove first entry from list
This removes the first (i.e. head) entry from the list
- Parameters
-
[in] list
Thread-safe, singly-linked list [out] entry_ptr
Pointer to hold removed entry
- Returns
- gos_result_t , result of API
◆ gos_safe_slinked_list_pop_multiple()
gos_result_t gos_safe_slinked_list_pop_multiple | ( | gos_safe_slinked_list_t * |
list,
|
void ** |
entries_ptr,
|
||
uint16_t |
max_count
|
||
) |
Remove multiple entries from list
This removes multiple entries from the head of the list.
- Parameters
-
[in] list
Thread-safe, singly-linked list [out] entries_ptr
Pointer to hold linked-list of entries removed from the head of the list [in] max_count
Maximum number of entries to remove
- Returns
- gos_result_t , result of API
◆ gos_safe_slinked_list_push()
gos_result_t gos_safe_slinked_list_push | ( | gos_safe_slinked_list_t * |
list,
|
void * |
entry
|
||
) |
Push entry to end of list
Push an entry to the end (i.e. tail) of the list
See gos_safe_slinked_list_entry_t for details about the entry's format.
- Parameters
-
[in] list
Thread-safe, singly-linked list [in] entry
Entry to push to entry of list
- Returns
- gos_result_t , result of API
◆ gos_safe_slinked_list_push_check_duplicate()
gos_result_t gos_safe_slinked_list_push_check_duplicate | ( | gos_safe_slinked_list_t * |
list,
|
void * |
entry,
|
||
gos_safe_slinked_list_callback_t |
callback,
|
||
void * |
user
|
||
) |
Push entry to end of list, checking for a duplicate first
If effectively calls:
i.e. Atomically, it first searches the list based on the provided callback and user argument If the search returns a match then a GOS_DUPLICATE result is returned. Otherwise the entry is added to the list.
See gos_safe_slinked_list_find_by() for more details on how the search is done.
- Note
-
The
callback
is invoked atomically and MUST NOT block!
- Parameters
-
[in] list
Thread-safe, singly-linked list [in] entry
Entry to add to list if it's not a duplicate [in] callback
Callback to be invoked for searching the list [in] user
User argument to provide to callback
- Returns
- gos_result_t , result of API
◆ gos_safe_slinked_list_push_multiple()
gos_result_t gos_safe_slinked_list_push_multiple | ( | gos_safe_slinked_list_t * |
list,
|
void * |
entries
|
||
) |
Push multiple entries to end of list
This pushes a linked-list of entries to the end (i.e. tail) of the list.
See gos_safe_slinked_list_entry_t for details about each entrys' format.
- Note
- If not all the entries will fit then NO entries will be added to the list.
- Parameters
-
[in] list
Thread-safe, singly-linked list [in] entries
Linked-list of entries to add to list
- Returns
- gos_result_t , result of API
◆ gos_safe_slinked_list_remove()
gos_result_t gos_safe_slinked_list_remove | ( | gos_safe_slinked_list_t * |
list,
|
void * |
entry
|
||
) |
Remove specific entry from list
Remove a specific entry from the list
- Parameters
-
[in] list
Thread-safe, singly-linked list [in] entry
Entry to remove from list
- Returns
- gos_result_t , result of API
◆ gos_safe_slinked_list_remove_at_index()
gos_result_t gos_safe_slinked_list_remove_at_index | ( | gos_safe_slinked_list_t * |
list,
|
uint32_t |
index,
|
||
void ** |
entry_ptr
|
||
) |
Remove entry at specific index
Optionally use GOS_SAFE_SLINKED_LIST_FIRST to remove the head entry of the list or GOS_SAFE_SLINKED_LIST_LAST to remove the tail of the list.
- Parameters
-
[in] list
Thread-safe, singly-linked list [in] index
Specific index of entry to remove [out] entry_ptr
Pointer to hold removed entry
- Returns
- gos_result_t , result of API
◆ gos_safe_slinked_list_remove_by()
gos_result_t gos_safe_slinked_list_remove_by | ( | gos_safe_slinked_list_t * |
list,
|
gos_safe_slinked_list_callback_t |
callback,
|
||
void * |
user,
|
||
void ** |
entry_ptr
|
||
) |
Remove entry by callback
This removes an entry based on the result of the given
callback
. If the
gos_safe_slinked_list_callback_t
returns
true
then the entry IS removed. If the
gos_safe_slinked_list_callback_t
returns
false
then the entry is NOT removed.
- Note
-
The
callback
is invoked atomically and MUST NOT block!
- Parameters
-
[in] list
Thread-safe, singly-linked list [in] callback
Callback to be invoked to determine if the entry should be removed [in] user
User argument provided to callback [out] entry_ptr
Pointer to hold removed entry
- Returns
- gos_result_t , result of API