function lfds710_btree_au_insert

From liblfds.org
Jump to navigation Jump to search

Source Files

└───liblfds710
    ├───inc
    │   └───liblfds710
    │           lfds710_btree_addonly_unbalanced.h
    └───src
        └───llfds710_btree_addonly_unbalanced
                lfds710_btree_addonly_unbalanced_insert.c

Opaque Structures

struct lfds710_btree_au_element;
struct lfds710_btree_au_state;

Enums

enum lfds710_btree_au_insert_result
{
  LFDS710_BTREE_AU_INSERT_RESULT_FAILURE_EXISTING_KEY,
  LFDS710_BTREE_AU_INSERT_RESULT_SUCCESS_OVERWRITE,
  LFDS710_BTREE_AU_INSERT_RESULT_SUCCESS
};

Prototype

enum lfds710_btree_au_insert_result lfds710_btree_au_insert_element( struct lfds710_btree_au_state *baus,
                                                                     struct lfds710_btree_au_element *baue,
                                                                     struct lfds710_btree_au_element **existing_baue );

Parameters

struct lfds710_btree_au_state *baus

A pointer to an initialized lfds710_btree_au_state.

struct lfds710_btree_au_element *baue

A pointer a user-allocated LFDS710_PAL_ATOMIC_ISOLATION_IN_BYTES aligned lfds710_btree_au_element. 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 lfds710_btree_au_element **existing_baue

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

Return Value

The return value is an enum lfds710_btree_au_insert_result.

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

If the key already exists in the btree, but LFDS710_BTREE_AU_EXISTING_KEY_OVERWRITE was specified to lfds710_btree_au_init_valid_on_current_logical_core when initializing the btree, the return value is LFDS710_BTREE_AU_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 btree, but LFDS710_BTREE_AU_EXISTING_KEY_FAIL was specified to lfds710_btree_au_init_valid_on_current_logical_core when initializing the btree, the return value is LFDS710_BTREE_AU_INSERT_RESULT_FAILURE_EXISTING_KEY (and the value in the existing key will be unchanged).

Notes

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

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

See Also