sys/atomicqueue.3

   1 .Dd May 26, 2004
   2 .Dt ATOMICQUEUE 3
   3 .Os Darwin
   4 .Sh NAME
   5 .Nm OSAtomicEnqueue ,
   6 .Nm OSAtomicDequeue
   7 .Nd atomic enqueue and dequeue on a singly linked list
   8 .Sh LIBRARY
   9 .Lb libc
  10 .Sh SYNOPSIS
  11 .In libkern/OSAtomic.h
  12 .Ft void
  13 .Fn OSAtomicEnqueue "void ** inList, void * inNewLink, size_t inOffset"
  14 .Ft void *
  15 .Fn OSAtomicDequeue "void ** inList, size_t inOffset"
  16 .Sh DESCRIPTION
  17 .Fn OSAtomicEnqueue
  18 and
  19 .Fn OSAtomicDequeue
  20 operate on zero-terminated singly-linked lists of structures whose
  21 link field need not be the first element.
  22 They are thread safe and incorporate memory barriers as required to
  23 synchronize access to the shared memory.  The list is last in, first out.
  24 .Pp
  25 If thread safety is not a requirement, then the queue(3) package is more
  26 flexible and possibly more efficient.
  27 .Pp
  28 .Fa inList
  29 is the pointer to the head of the list.  It is not a structure, and should be
  30 initialized to
  31 .Dv NIL .
  32 .Fa inOffset
  33 is the offset within the structure of the link field.
  34 .Fa inNewLink
  35 is a pointer to the structure to be queued on the list:
  36 .Bd -literal -offset indent
  37 typedef struct node {
  38     long    data1;
  39     struct  node *link;
  40     int     data2;
  41 } node;
  42
  43 node    *head = NIL;
  44 node    n1, n2;
  45 node    *p;
  46
  47 /* put n1 on the list */
  48 OSAtomicEnqueue( (void**) &head, &n1, offsetof(node,link));
  49
  50 /* then put n2 on the list */
  51 OSAtomicEnqueue( (void**) &head, &n2, offsetof(node,link));
  52
  53 /* dequeue n2 (ie, the node most recently added) */
  54 p = OSAtomicDequeue( (void**) &head, offsetof(node,link));
  55 .Ed
  56 .Sh RETURN VALUES
  57 .Fn OSAtomicDequeue
  58 returns a pointer to the node removed from the list, or
  59 .Dv NIL
  60 if the list is empty.
  61 .Sh SEE ALSO
  62 .Xr atomic 3 ,
  63 .Xr spinlock 3 ,
  64 .Xr barrier 3 ,
  65 .Xr queue 3