Singly-Linked List
Utilities > Thread-Safe Objects

Singly-Linked List. More...

Modules

Types
Singly-Linked List data types.
 
Macros
Singly-Linked List data macros.
 

Functions

gos_result_t gos_safe_slinked_list_init (gos_safe_slinked_list_t *list, uint16_t max_count)
 
gos_result_t gos_safe_slinked_list_push (gos_safe_slinked_list_t *list, void *entry)
 
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)
 
gos_result_t gos_safe_slinked_list_push_multiple (gos_safe_slinked_list_t *list, void *entries)
 
gos_result_t gos_safe_slinked_list_pop (gos_safe_slinked_list_t *list, void **entry_ptr)
 
gos_result_t gos_safe_slinked_list_pop_multiple (gos_safe_slinked_list_t *list, void **entries_ptr, uint16_t max_count)
 
gos_result_t gos_safe_slinked_list_add_at_index (gos_safe_slinked_list_t *list, uint32_t index, void *entry)
 
gos_result_t gos_safe_slinked_list_remove (gos_safe_slinked_list_t *list, void *entry)
 
gos_result_t gos_safe_slinked_list_remove_at_index (gos_safe_slinked_list_t *list, uint32_t index, void **entry_ptr)
 
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)
 
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)
 
void gos_safe_slinked_list_flush (gos_safe_slinked_list_t *list, gos_safe_slinked_list_callback_t callback, void *user)
 
bool gos_safe_slinked_list_is_empty (const gos_safe_slinked_list_t *list)
 
bool gos_safe_slinked_list_is_full (const gos_safe_slinked_list_t *list)
 
uint16_t gos_safe_slinked_list_get_count (const gos_safe_slinked_list_t *list)
 
uint16_t gos_safe_slinked_list_get_free_space_count (const gos_safe_slinked_list_t *list)
 

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:

typedef struct gos_safe_slinked_list_entry
{
struct gos_safe_slinked_list_entry *next;
} gos_safe_slinked_list_entry_t;

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:

typedef struct my_list_entry
{
struct my_list_entry *next;
uint32_t my_timestamp;
char some_buffer[8];
bool some_flag;
} my_list_entry_t;

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]listThread-safe, singly-linked list
[in]indexIndex to insert entry into list
[in]entryEntry 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]listThread-safe, singly-linked list
[in]callbackCallback to be invoked to determine if the entry is found
[in]userUser argument provided to callback
[out]entry_ptrPointer 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]listThread-safe, singly-linked list
[in]callbackCallback to be invoked for each entry in the list
[in]userUser 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]listThread-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]listThread-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]listList to initialize
[in]max_countMaximum 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]listThread-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]listThread-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]listThread-safe, singly-linked list
[out]entry_ptrPointer 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]listThread-safe, singly-linked list
[out]entries_ptrPointer to hold linked-list of entries removed from the head of the list
[in]max_countMaximum 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]listThread-safe, singly-linked list
[in]entryEntry 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:

ATOMIC_START()
if(gos_safe_slinked_list_find_by(list, callback, user, NULL) == GOS_SUCCESS)
{
ATOMIC_END()
return GOS_DUPLICATE
}
gos_safe_slinked_list_push(list, entry)
ATOMIC_END()

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]listThread-safe, singly-linked list
[in]entryEntry to add to list if it's not a duplicate
[in]callbackCallback to be invoked for searching the list
[in]userUser 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]listThread-safe, singly-linked list
[in]entriesLinked-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]listThread-safe, singly-linked list
[in]entryEntry 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]listThread-safe, singly-linked list
[in]indexSpecific index of entry to remove
[out]entry_ptrPointer 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]listThread-safe, singly-linked list
[in]callbackCallback to be invoked to determine if the entry should be removed
[in]userUser argument provided to callback
[out]entry_ptrPointer to hold removed entry
Returns
gos_result_t, result of API