function lfds700_hash_a_insert

Source Files

└───liblfds700
    ├───inc
    │   └───liblfds700
    │           lfds700_hash_addonly.h
    └───src
        └───llfds700_freelist
                lfds700_hash_addonly_insert.c

Enums

enum lfds700_hash_a_insert_result
{
  LFDS700_HASH_A_INSERT_RESULT_FAILURE_EXISTING_KEY,
  LFDS700_HASH_A_INSERT_RESULT_SUCCESS_OVERWRITE,
  LFDS700_HASH_A_INSERT_RESULT_SUCCESS
};

Opaque Structures

struct lfds700_hash_a_element;
struct lfds700_hash_a_state;
struct lfds700_misc_prng_state;

Prototype

enum lfds700_hash_a_insert_result lfds700_hash_a_insert( struct lfds700_hash_a_state *has,
                                                         struct lfds700_hash_a_element *hae,
                                                         struct lfds700_hash_a_element **existing_hae,
                                                         struct lfds700_misc_prng_state *ps );

Parameters

struct lfds700_hash_a_state *has

A pointer to an initialized struct lfds700_hash_a_state.

struct lfds700_hash_a_element *hae

A pointer to a user-allocated LFDS700_PAL_ATOMIC_ISOLATION_IN_BYTES aligned struct lfds700_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 lfds700_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).

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_hash_a_insert_result.

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

If the key already exists in the hash, but LFDS700_HASH_A_EXISTING_KEY_OVERWRITE was specified to lfds700_hash_a_init_valid_on_current_logical_core when initializing the hash, the return value is LFDS700_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 btree, but LFDS700_HASH_A_EXISTING_KEY_FAIL was specified to lfds700_hash_a_init_valid_on_current_logical_core when initializing the btree, the return value is LFDS700_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 lfds700_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.

Example

#include <stdio.h>
#include <string.h>
#include "liblfds700.h"

struct test_data
{
  int long long unsigned
    unique_id;

  char
    payload[64];

  struct lfds700_hash_a_element
    hae;
};

int key_compare_function( void const *new_key, void const *existing_key )
{
  int
    cr = 0;

  int long long unsigned
    *new_key = (int long long unsigned *) new_key,
    *existing_key  = (int long long unsigned *) existing_key;

  if( *new_key > *existing_key )
    cr = 1;

  if( *new_key < *existing_key )
    cr = -1;

  return( cr );
}

void key_hash_function( void const *key, lfds700_pal_uint_t *hash )
{
  int unsigned
    temp_hash = 0;

  LFDS700_HASH_A_32BIT_HASH_FUNCTION( key, sizeof(int long long unsigned), temp_hash );

  *hash = temp_hash;

  return;
}

int main()
{
  struct lfds700_btree_au_state
    baus_array[10];

  struct lfds700_hash_a_element
    *hae;

  struct lfds700_hash_a_state
    has;

  struct lfds700_misc_prng_state
    ps;

  struct test_data
    td,
    *temp_td;

  lfds700_misc_library_init_valid_on_current_logical_core();

  lfds700_misc_prng_init( &ps );

  lfds700_hash_a_init_valid_on_current_logical_core( &has, baus_array, 10, key_compare_function, key_hash_function, LFDS700_HASH_A_EXISTING_KEY_FAIL, NULL );

  td.unique_id = 15;
  strcpy( td.payload, "Linear A" );

  LFDS700_HASH_A_SET_KEY_IN_ELEMENT( td.hae, &td.unique_id );
  LFDS700_HASH_A_SET_VALUE_IN_ELEMENT( td.hae, &td );
  lfds700_hash_a_insert_element( &has, &hae, NULL, &ps );
 
  lfds700_hash_a_cleanup( &has, NULL );

  lfds700_misc_library_cleanup();

  return( EXIT_SUCCESS );
}

function lfds700_hash_a_insert

Contents