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] 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:

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] 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