man/atomic.3

   1 .Dd May 26, 2004
   2 .Dt ATOMIC 3
   3 .Os Darwin
   4 .Sh NAME
   5 .Nm OSAtomicEnqueue ,
   6 .Nm OSAtomicDequeue
   7 .Nd atomic lockless queues
   8 .Sh SYNOPSIS
   9 .In libkern/OSAtomic.h
  10 .Ft void
  11 .Fn OSAtomicEnqueue "OSQueueHead *list" "void *new" "size_t offset"
  12 .Ft void*
  13 .Fn OSAtomicDequeue "OSQueueHead *list" "size_t offset"
  14 .Sh DESCRIPTION
  15 The routines
  16 .Fn OSAtomicEnqueue
  17 and
  18 .Fn OSAtomicDequeue
  19 operate on singly linked LIFO queues.  Ie, a dequeue operation will return the
  20 most recently enqueued element, or NULL if the list is empty.  The operations
  21 are lockless, and barriers are used as necessary to permit thread-safe access to
  22 the queue element.
  23 .Fa offset
  24 is the offset in bytes to the link field in the queue element.
  25 .Pp
  26 .Bf -symbolic
  27 Important: the memory backing the link field of a queue element must not be
  28 unmapped after
  29 .Fn OSAtomicDequeue
  30 returns until all concurrent calls to
  31 .Fn OSAtomicDequeue
  32 for the same list on other threads have also returned, as they may still be
  33 accessing that memory location.
  34 .Ef
  35 .Sh EXAMPLES
  36 .Bd -literal -offset indent
  37         typedef struct elem {
  38                 long    data1;
  39                 struct elem *link;
  40                 int     data2;
  41         } elem_t;
  42
  43         elem_t fred, mary, *p;
  44
  45         OSQueueHead q = OS_ATOMIC_QUEUE_INIT;
  46
  47         OSAtomicEnqueue( &q, &fred, offsetof(elem_t,link) );
  48         OSAtomicEnqueue( &q, &mary, offsetof(elem_t,link) );
  49
  50         p = OSAtomicDequeue( &q, offsetof(elem_t,link) );
  51
  52 .Ed
  53 In this example, the call of
  54 .Fn OSAtomicDequeue
  55 will return a ptr to mary.
  56 .Sh RETURN VALUES
  57 The dequeue operation returns the most recently enqueued element, or NULL if the list in empty.
  58 .Sh SEE ALSO
  59 .Xr stdatomic 3 ,
  60 .Xr atomic_deprecated 3 ,
  61 .Xr spinlock_deprecated 3
  62 .Sh HISTORY
  63 These functions first appeared in Mac OS 10.5 (Leopard).