ATOMICQUEUE(3)

NAME
OSAtomicEnqueue, OSAtomicDequeue - atomic enqueue and dequeue on a singly linked list

LIBRARY
libc

SYNOPSIS
#include <libkern/OSAtomic.h>
void
OSAtomicEnqueue(void ** inList, void * inNewLink, size_t inOffset);
void *
OSAtomicDequeue(void ** inList, size_t inOffset);

DESCRIPTION
OSAtomicEnqueue() and OSAtomicDequeue() operate on zero-terminated singly-linked lists of structures whose link field need not be the first element. They are thread safe and incorporate memory barriers as required to synchronize access to the shared memory. The list is last in, first out.

If thread safety is not a requirement, then the queue(3) package is more flexible and possibly more efficient.

inList is the pointer to the head of the list. It is not a structure, and should be initialized to NIL. inOffset is the offset within the structure of the link field. inNewLink is a pointer to the structure to be queued on the list:

    typedef struct node {
        long    data1;
        struct  node *link;
        int     data2;
    } node;
    node    *head = NIL;
    node    n1, n2;
    node    *p;
    /* put n1 on the list */
    OSAtomicEnqueue( (void**) &head, &n1, offsetof(node,link));
    /* then put n2 on the list */
    OSAtomicEnqueue( (void**) &head, &n2, offsetof(node,link));
    /* dequeue n2 (ie, the node most recently added) */
    p = OSAtomicDequeue( (void**) &head, offsetof(node,link));

RETURN VALUES
OSAtomicDequeue() returns a pointer to the node removed from the list, or NIL if the list is empty.

SEE ALSO
atomic(3), spinlock(3), barrier(3), queue(3)