function lfds711_list_aso_init_valid_on_current_logical_core

From liblfds.org
Revision as of 18:11, 16 February 2017 by Admin (talk | contribs) (1 revision imported)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Source Files

└───liblfds711
    ├───inc
    │   └───liblfds711
    │           lfds711_list_addonly_singlylinked._orderedh
    └───src
        └───llfds711_list_addonly_singlylinked_ordered
                lfds711_list_addonly_singlylinked_ordered_init.c

Enums

enum lfds711_list_aso_existing_key
{
  LFDS711_LIST_ASO_EXISTING_KEY_OVERWRITE,
  LFDS711_LIST_ASO_EXISTING_KEY_FAIL
};

Opaque Structures

struct lfds711_list_aso_state;

Prototype

void lfds711_list_aso_init( struct lfds711_list_aso_state *lasos,
                            int (*key_compare_function)(void const *new_key, void const *existing_key),
                            enum lfds711_list_aso_existing_key existing_key,
                            void *user_state );

Parameters

struct lfds711_list_aso_state *lasos

A pointer to a user-allocated LFDS711_PAL_ATOMIC_ISOLATION_IN_BYTES aligned struct lfds711_list_aso_state. 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.

int (*key_compare_function)(void const *new_key, void const *existing_key)

A callback used by the list to compare keys. The callback returns 0 if the keys are equal, smaller than zero if new_key is smaller than existing_key and greater than zero if new_key is greater than existing_key (i.e. as strcmp).

enum lfds711_list_aso_existing_key existing_key

This argument specifies how the list should behave when attempting to add a key which already exists (see Notes).

void *user_state

A pointer to void, supplied by the user, which is returned to the user in various callback functions, permitting the user to pass his own state into those functions. This argument can be NULL.

Notes

As the function name indicates, the initialization work performed on the list state is only valid on the current logical core. To make this work valid on other logical cores, threads on other cores must call LFDS711_MISC_MAKE_VALID_ON_CURRENT_LOGICAL_CORE_INITS_COMPLETED_BEFORE_NOW_ON_ANY_OTHER_LOGICAL_CORE.

This function instantiates an add-only, ordered, singly-linked list by initializing the list state. The caller is responsible for all memory allocation and, after lfds711_list_aso_cleanup is called, for all deallocation.

The existing_key argument specifies how lfds711_list_aso_insert should behave when the attempt is made to add a new element which has a key which is already present in the btree.

If LFDS711_LIST_ASO_EXISTING_KEY_FAIL is specified, lfds711_list_aso_insert will fail, and return LFDS711_LIST_ASO_LINK_RESULT_FAILURE_EXISTING_KEY.

If LFDS711_LIST_ASO_EXISTING_KEY_OVERWRITE is specified, the attempt will cause the value in the new element to over-write that of the existing element, and lfds711_list_aso_insert will return LFDS711_LIST_ASO_LINK_RESULT_SUCCESS_OVERWRITE.

(In both cases, when a linking a key which is not present in the list, LFDS711_BTREE_AU_LINK_RESULT_SUCCESS is returned.)

See Also