SMR_LIST_INIT(9)

NAME
SMR_SLIST_ENTRY, SMR_SLIST_HEAD, SMR_SLIST_HEAD_INITIALIZER, SMR_SLIST_INIT, SMR_SLIST_FIRST, SMR_SLIST_NEXT, SMR_SLIST_FOREACH, SMR_SLIST_FIRST_LOCKED, SMR_SLIST_NEXT_LOCKED, SMR_SLIST_EMPTY_LOCKED, SMR_SLIST_FOREACH_LOCKED, SMR_SLIST_FOREACH_SAFE_LOCKED, SMR_SLIST_INSERT_HEAD_LOCKED, SMR_SLIST_INSERT_AFTER_LOCKED, SMR_SLIST_REMOVE_HEAD_LOCKED, SMR_SLIST_REMOVE_AFTER_LOCKED, SMR_SLIST_REMOVE_LOCKED, SMR_LIST_ENTRY, SMR_LIST_HEAD, SMR_LIST_HEAD_INITIALIZER, SMR_LIST_INIT, SMR_LIST_FIRST, SMR_LIST_NEXT, SMR_LIST_FOREACH, SMR_LIST_FIRST_LOCKED, SMR_LIST_NEXT_LOCKED, SMR_LIST_EMPTY_LOCKED, SMR_LIST_FOREACH_LOCKED, SMR_LIST_FOREACH_SAFE_LOCKED, SMR_LIST_INSERT_HEAD_LOCKED, SMR_LIST_INSERT_AFTER_LOCKED, SMR_LIST_INSERT_BEFORE_LOCKED, SMR_LIST_REMOVE_LOCKED - SMR list macros

SYNOPSIS
#include <sys/smr.h>
void
SMR_SLIST_INIT(SMR_SLIST_HEAD *head);
TYPE *
SMR_SLIST_FIRST(SMR_SLIST_HEAD *head);
TYPE *
SMR_SLIST_NEXT(TYPE *elm, FIELDNAME);
SMR_SLIST_FOREACH(VARNAME, SMR_SLIST_HEAD *head, FIELDNAME);
TYPE *
SMR_SLIST_FIRST_LOCKED(SMR_SLIST_HEAD *head);
TYPE *
SMR_SLIST_NEXT_LOCKED(TYPE *elm, FIELDNAME);
int
SMR_SLIST_EMPTY_LOCKED(SMR_SLIST_HEAD *head);
SMR_SLIST_FOREACH_LOCKED(VARNAME, SMR_SLIST_HEAD *head, FIELDNAME);
SMR_SLIST_FOREACH_SAFE_LOCKED(VARNAME, SMR_LIST_HEAD *head, FIELDNAME, TEMP_VARNAME);
void
SMR_SLIST_INSERT_HEAD_LOCKED(SMR_SLIST_HEAD *head, struct TYPE *elm, FIELDNAME);
void
SMR_SLIST_INSERT_AFTER_LOCKED(struct TYPE *listelm, struct TYPE *elm, FIELDNAME);
void
SMR_SLIST_REMOVE_HEAD_LOCKED(SMR_SLIST_HEAD *head, FIELDNAME);
void
SMR_SLIST_REMOVE_AFTER_LOCKED(struct TYPE *elm, FIELDNAME);
void
SMR_SLIST_REMOVE_LOCKED(SMR_SLIST_HEAD *head, struct TYPE *elm, TYPE, FIELDNAME);
void
SMR_LIST_INIT(SMR_LIST_HEAD *head);
TYPE *
SMR_LIST_FIRST(SMR_LIST_HEAD *head);
TYPE *
SMR_LIST_NEXT(TYPE *elm, FIELDNAME);
TYPE *
SMR_LIST_FIRST_LOCKED(SMR_LIST_HEAD *head);
TYPE *
SMR_LIST_NEXT_LOCKED(TYPE *elm, FIELDNAME);
int
SMR_LIST_EMPTY_LOCKED(SMR_LIST_HEAD *head);
SMR_LIST_FOREACH(VARNAME, SMR_LIST_HEAD *head, FIELDNAME);
SMR_LIST_FOREACH_LOCKED(VARNAME, SMR_LIST_HEAD *head, FIELDNAME);
SMR_LIST_FOREACH_SAFE_LOCKED(VARNAME, SMR_LIST_HEAD *head, FIELDNAME, TEMP_VARNAME);
void
SMR_LIST_INSERT_HEAD_LOCKED(SMR_LIST_HEAD *head, struct TYPE *elm, FIELDNAME);
void
SMR_LIST_INSERT_AFTER_LOCKED(struct TYPE *listelm, struct TYPE *elm, FIELDNAME);
void
SMR_LIST_INSERT_BEFORE_LOCKED(struct TYPE *listelm, struct TYPE *elm, FIELDNAME);
void
SMR_LIST_REMOVE_LOCKED(struct TYPE *elm, FIELDNAME);

DESCRIPTION
The SMR list macros define and operate on singly-linked lists and lists that can be used with the safe memory reclamation mechanism. A data structure built with these macros can be accessed concurrently by multiple readers and a single writer.

Readers have to access the data structure inside SMR read-side critical section. The critical section is entered using smr_read_enter(9), and left using smr_read_leave(9).

Writers must ensure exclusive write access. That can be done using a lock, such as mutex(9) or rwlock(9). The mutual exclusion of writers does not need to apply to readers.

When an element has been removed from the data structure, the element must not be deleted or re-inserted before all reader references to it have disappeared. The writer has to use either smr_barrier(9) or smr_call(9) to ensure that the element can no longer be accessed by readers.

SINGLY-LINKED LISTS
SMR_SLIST_INIT() initialies the list head to an empty state.

SMR_SLIST_FIRST() and SMR_SLIST_FIRST_LOCKED() return the first element on the list head, or NULL if the list is empty.

SMR_SLIST_NEXT() and SMR_SLIST_NEXT_LOCKED() return the successor of the element elm, or NULL if there are no more elements on the list.

SMR_SLIST_EMPTY_LOCKED() returns true of the list head is empty.

SMR_SLIST_FOREACH() and SMR_SLIST_FOREACH_LOCKED() traverse the list head in forward direction.

SMR_SLIST_FOREACH_SAFE_LOCKED() traverses the list head in forward direction. It is permitted to remove the element referenced by variable VARNAME from the list and defer its freeing using smr_call(9).

SMR_SLIST_INSERT_HEAD_LOCKED() inserts the new element elm at the head of the list.

SMR_SLIST_INSERT_AFTER_LOCKED() inserts the new element elm after the element listelm.

SMR_SLIST_REMOVE_HEAD_LOCKED() removes the first element of the list head.

SMR_SLIST_REMOVE_AFTER_LOCKED() removes the list element immediately following elm.

SMR_SLIST_REMOVE_LOCKED() removes the list element elm from the list head.

LISTS
SMR_LIST_INIT() initialies the list head to an empty state.

SMR_LIST_FIRST() and SMR_LIST_FIRST_LOCKED() return the first element on the list head, or NULL if the list is empty.

SMR_LIST_NEXT() and SMR_LIST_NEXT_LOCKED() return the successor of the element elm, or NULL if there are no more elements on the list.

SMR_SLIST_EMPTY_LOCKED() returns true of the list head is empty.

SMR_LIST_FOREACH() and SMR_LIST_FOREACH_LOCKED() traverse the list head in forward direction.

SMR_LIST_FOREACH_SAFE_LOCKED() traverses the list head in forward direction. It is permitted to remove the element referenced by variable VARNAME from the list and defer its freeing using smr_call(9).

SMR_LIST_INSERT_HEAD_LOCKED() inserts the new element elm at the head of the list.

SMR_LIST_INSERT_AFTER_LOCKED() inserts the new element elm after the element listelm.

SMR_LIST_INSERT_BEFORE_LOCKED() inserts the new element elm before the element listelm.

SMR_LIST_REMOVE_LOCKED() removes the element elm from the list head.

CONTEXT
SMR_SLIST_FIRST, SMR_SLIST_NEXT, SMR_SLIST_FOREACH, SMR_SLIST_INIT, SMR_SLIST_FIRST_LOCKED, SMR_SLIST_NEXT_LOCKED, SMR_SLIST_EMPTY_LOCKED, SMR_SLIST_FOREACH_LOCKED, SMR_SLIST_FOREACH_SAFE_LOCKED, SMR_SLIST_INSERT_HEAD_LOCKED, SMR_SLIST_INSERT_AFTER_LOCKED, SMR_SLIST_REMOVE_HEAD_LOCKED, SMR_SLIST_REMOVE_AFTER_LOCKED, SMR_SLIST_REMOVE_LOCKED, SMR_LIST_FIRST, SMR_LIST_NEXT, SMR_LIST_FOREACH, SMR_LIST_INIT, SMR_LIST_FIRST_LOCKED, SMR_LIST_NEXT_LOCKED, SMR_LIST_EMPTY_LOCKED, SMR_LIST_FOREACH_LOCKED, SMR_LIST_FOREACH_SAFE_LOCKED, SMR_LIST_INSERT_HEAD_LOCKED, SMR_LIST_INSERT_AFTER_LOCKED, SMR_LIST_INSERT_BEFORE_LOCKED and SMR_LIST_REMOVE_LOCKED can be used during autoconf, from process context, or from interrupt context.

SMR_SLIST_FIRST, SMR_SLIST_NEXT, SMR_SLIST_FOREACH, SMR_LIST_FIRST, SMR_LIST_NEXT and SMR_LIST_FOREACH can be used from SMR read-side critical section.

SMR_SLIST_INIT, SMR_SLIST_FIRST_LOCKED, SMR_SLIST_NEXT_LOCKED, SMR_SLIST_EMPTY_LOCKED, SMR_SLIST_FOREACH_LOCKED, SMR_SLIST_FOREACH_SAFE_LOCKED, SMR_SLIST_INSERT_HEAD_LOCKED, SMR_SLIST_INSERT_AFTER_LOCKED, SMR_SLIST_REMOVE_HEAD_LOCKED, SMR_SLIST_REMOVE_AFTER_LOCKED, SMR_SLIST_REMOVE_LOCKED, SMR_LIST_INIT, SMR_LIST_FIRST_LOCKED, SMR_LIST_NEXT_LOCKED, SMR_LIST_EMPTY_LOCKED, SMR_LIST_FOREACH_LOCKED, SMR_LIST_FOREACH_SAFE_LOCKED, SMR_LIST_INSERT_HEAD_LOCKED, SMR_LIST_INSERT_AFTER_LOCKED, SMR_LIST_INSERT_BEFORE_LOCKED and SMR_LIST_REMOVE_LOCKED can be used from writer context.

SEE ALSO
queue(3), smr_call(9), smr_read_enter(9)

HISTORY
The SMR list macros first appeared in OpenBSD 6.5.