[apple/libplatform.git] / man / atomic.3

.Dd May 26, 2004
.Dt ATOMIC 3
.Os Darwin
.Sh NAME
.Nm OSAtomicEnqueue ,
.Nm OSAtomicDequeue
.Nd atomic lockless queues
.Sh SYNOPSIS
.In libkern/OSAtomic.h
.Ft void
.Fn OSAtomicEnqueue "OSQueueHead *list" "void *new" "size_t offset"
.Ft void*
.Fn OSAtomicDequeue "OSQueueHead *list" "size_t offset"
.Sh DESCRIPTION
The routines
.Fn OSAtomicEnqueue
and
.Fn OSAtomicDequeue
operate on singly linked LIFO queues.  Ie, a dequeue operation will return the
most recently enqueued element, or NULL if the list is empty.  The operations
are lockless, and barriers are used as necessary to permit thread-safe access to
the queue element.
.Fa offset
is the offset in bytes to the link field in the queue element.
.Pp
.Bf -symbolic
Important: the memory backing the link field of a queue element must not be
unmapped after
.Fn OSAtomicDequeue
returns until all concurrent calls to
.Fn OSAtomicDequeue
for the same list on other threads have also returned, as they may still be
accessing that memory location.
.Ef
.Sh EXAMPLES
.Bd -literal -offset indent
	typedef struct elem {
		long	data1;
		struct elem *link;
		int	data2;
	} elem_t;
	
	elem_t fred, mary, *p;
	
	OSQueueHead q = OS_ATOMIC_QUEUE_INIT;
	
	OSAtomicEnqueue( &q, &fred, offsetof(elem_t,link) );
	OSAtomicEnqueue( &q, &mary, offsetof(elem_t,link) );
	
	p = OSAtomicDequeue( &q, offsetof(elem_t,link) );
	
.Ed
In this example, the call of
.Fn OSAtomicDequeue
will return a ptr to mary.
.Sh RETURN VALUES
The dequeue operation returns the most recently enqueued element, or NULL if the list in empty.
.Sh SEE ALSO
.Xr stdatomic 3 ,
.Xr atomic_deprecated 3 ,
.Xr spinlock_deprecated 3
.Sh HISTORY
These functions first appeared in Mac OS 10.5 (Leopard).
Commit	Line	Data
ada7c492 A	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
e45b4692	59	.Xr stdatomic 3 ,
ada7c492 A	60	.Xr atomic_deprecated 3 ,
	61	.Xr spinlock_deprecated 3
	62	.Sh HISTORY
	63	These functions first appeared in Mac OS 10.5 (Leopard).