function lfds700_list_aos_insert

Source Files

└───liblfds700
    ├───inc
    │   └───liblfds700
    │           lfds700_list_addonly_ordered_singlylinked.h
    └───src
        └───llfds700_list_addonly_ordered_singlylinked
                lfds700_list_addonly_ordered_singlylinked_insert.c

Opaque Structures

struct lfds700_list_aos_element;
struct lfds700_list_aos_state;
struct lfds700_misc_prng_state;

Prototype

enum lfds700_list_aos_insert_result lfds700_list_aos_insert( struct lfds700_list_aos_state *laoss,
                                                             struct lfds700_list_aos_element *laose,
                                                             struct lfds700_list_aos_element **existing_laose,
                                                             struct lfds700_misc_prng_state *ps );

Parameters

struct lfds700_list_aos_state *laoss

A pointer to an initialized struct lfds700_list_aos_state.

struct lfds700_list_aos_element *laose

A pointer a user-allocated LFDS700_PAL_ATOMIC_ISOLATION_IN_BYTES aligned struct lfds700_list_aos_element, which will be inserted into the list. Stack declared variables will automatically be correctly aligned by the compiler, due to the information in the structure definitions; nothing has to be done. Heap allocated variables however will by no means be correctly aligned and an aligned malloc must be used.

struct lfds700_list_aos_element **existing_laose

If on put the key already exists, *existing_laose is set to point to the existing element with that key. This argument can be NULL (and then is unused).

struct lfds700_misc_prng_state *ps

A pointer to an initialized struct lfds700_misc_prng_state.

Return Value

The return value is an enum lfds700_list_aos_insert_result.

If the key did not exist in the list, and so was successfully linked, the return value is LFDS700_LIST_AOS_INSERT_RESULT_SUCCESS.

If the key already exists in the list, but LFDS700_LIST_AOS_EXISTING_KEY_OVERWRITE was specified to lfds700_list_aos_init_valid_on_current_logical_core when initializing the list, the return value is LFDS700_LIST_AOS_INSERT_RESULT_SUCCESS_OVERWRITE (and the value in the existing key will have been overwritten with the value in the new key).

If the key already exists in the list, but LFDS700_LIST_AOS_EXISTING_KEY_FAIL was specified to lfds700_list_aos_init_valid_on_current_logical_core when initializing the list, the return value is LFDS700_LIST_AOS_INSERT_RESULT_FAILURE_EXISTING_KEY (and the value in the existing key will be unchanged).

Notes

This function takes a user allocated struct lfds700_list_aos_element, which the user has with the list macros populated with a key (and typically but optionally with a value), and inserts this element into the list, using the key_compare_function callback to compare list element keys to find the correct position in the btree.

If when inserting a new element the key is already present in the list, the argument *existing_laose, if not NULL, will be set to point to the existing element.

Example

Coming soon. No, really! (Written 29th Dec 2015).

function lfds700_list_aos_insert

Contents