function lfds711_hash_a_insert

From liblfds.org
Jump to navigation Jump to search

Source Files

└───liblfds711
    ├───inc
    │   └───liblfds711
    │           lfds711_hash_addonly.h
    └───src
        └───llfds711_freelist
                lfds711_hash_addonly_insert.c

Enums

enum lfds711_hash_a_insert_result
{
  LFDS711_HASH_A_INSERT_RESULT_FAILURE_EXISTING_KEY,
  LFDS711_HASH_A_INSERT_RESULT_SUCCESS_OVERWRITE,
  LFDS711_HASH_A_INSERT_RESULT_SUCCESS
};

Opaque Structures

struct lfds711_hash_a_element;
struct lfds711_hash_a_state;

Prototype

enum lfds711_hash_a_insert_result lfds711_hash_a_insert( struct lfds711_hash_a_state *has,
                                                         struct lfds711_hash_a_element *hae,
                                                         struct lfds711_hash_a_element **existing_hae );

Parameters

struct lfds711_hash_a_state *has

A pointer to an initialized struct lfds711_hash_a_state.

struct lfds711_hash_a_element *hae

A pointer to a user-allocated LFDS711_PAL_ATOMIC_ISOLATION_IN_BYTES aligned struct lfds711_hash_a_element to add to the hash. 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 lfds711_hash_a_element **existing_hae

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

Return Value

The return value is an enum lfds711_hash_a_insert_result.

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

If the key already exists in the hash, but LFDS711_HASH_A_EXISTING_KEY_OVERWRITE was specified to lfds711_hash_a_init_valid_on_current_logical_core when initializing the hash, the return value is LFDS711_HASH_A_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 hash, but LFDS711_HASH_A_EXISTING_KEY_FAIL was specified to lfds711_hash_a_init_valid_on_current_logical_core when initializing the btree, the return value is LFDS711_HASH_A_INSERT_RESULT_FAILURE_EXISTING_KEY (and the value in the existing key will be unchanged).

Notes

This function takes a user allocated struct lfds711_hash_a_element, which the user has with the hash macros populated with a key (and typically but not manditatorially with a value), and links this element into the hash, using the key_compare_function callback to compare hash element keys to find the correct position in the hash.

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

See Also