r6.0.1:lfds601_slist

Source Files

/liblfds601/src/lfds601_slist/lfds601_slist_delete.c
/liblfds601/src/lfds601_slist/lfds601_slist_get_and_set.c
/liblfds601/src/lfds601_slist/lfds601_slist_link.c
/liblfds601/src/lfds601_slist/lfds601_slist_new.c
/liblfds601/src/lfds601_slist/lfds601_slist_internal.h
/liblfds601/inc/liblfds601.h

Incomplete Types

struct lfds601_slist_state;
struct lfds601_slist_element;

Prototypes

int lfds601_slist_new( struct lfds601_slist_state **ss,
                       void (*user_data_delete_function)(void *user_data, void *user_state),
                       void *user_state );
void lfds601_slist_delete( struct lfds601_slist_state *ss );

struct lfds601_slist_element *lfds601_slist_new_head( struct lfds601_slist_state *ss, void *user_data );
struct lfds601_slist_element *lfds601_slist_new_next( struct lfds601_slist_element *se, void *user_data );

void lfds601_slist_delete_element( struct lfds601_slist_state *ss, struct lfds601_slist_element *se );
void lfds601_slist_delete_all_elements( struct lfds601_slist_state *ss );

int lfds601_slist_get_user_data_from_element( struct lfds601_slist_element *se, void **user_data );
int lfds601_slist_set_user_data_in_element( struct lfds601_slist_element *se, void *user_data );

struct lfds601_slist_element *lfds601_slist_get_head( struct lfds601_slist_state *ss, struct lfds601_slist_element **se );
struct lfds601_slist_element *lfds601_slist_get_next( struct lfds601_slist_element *se, struct lfds601_slist_element *next_se );
struct lfds601_slist_element *lfds601_slist_get_head_and_then_next( struct lfds601_slist_state *ss, struct lfds601_slist_element **se );

Overview

This API implements a singly linked list which does not support genuine delete, but only logical delete; when an element is deleted by the lfds601_slist_delete_element function, it is logically deleted - all operations on the list will be as if the element was truly deleted - but not physically deleted, so it remains in the list and is not deallocated. (It is safe to call lfds601_slist_get_next on a logically deleted element). Elements are only actually freed when the list is deleted or when the lfds601_slist_delete_all_elements function is called and this latter function is not thread safe.

This API implements a singly linked list. A new list is instantiated by the lfds601_slist_new function. The caller then uses the list by adding or deleting elements, or by traversing the list, via the lfds601_slist_new_head, lfds601_slist_new_next and lfds601_slist_delete_element functions for adding and deleting and the lfds601_slist_get_head, lfds601_slist_get_next and lfds601_slist_get_head_and_then_next functions for traversing. An add or delete will add or delete a single list element. Each traverse function returns a pointer to a list element. A list element contains a single void pointer of user data, which is read and written using the functions lfds601_slist_get_user_data_from_element and lfds601_slist_get_user_data_from_element, respectively. These void pointers are expected to point to user allocated state although of course they can be used directly to store a single value. Finally, the list is deleted using lfds601_slist_delete.

Lock-free Specific Behaviour

It is not possible to actually delete individual elements, only to logically delete them. As such the list can only grow. The slist can be cleared, which does delete all elements.

Algorithm

The singly linked list algorithm is sufficiently obvious that I've implemented it from scratch. Valois (1995) describes a lock-free singly linked list which supports true delete. I will be implementing this, but it will take time and I need a singly linked list now (add-only being adequate), which is why this list is now available. Implementing Valois' list will I believe cause API changes since he uses cursors.