/* * Copyright (c) 2004-2016 Apple Inc. All rights reserved. * * @APPLE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this * file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_LICENSE_HEADER_END@ */ #ifndef _OSATOMICQUEUE_H_ #define _OSATOMICQUEUE_H_ #include <stddef.h> #include <sys/cdefs.h> #include <stdint.h> #include <stdbool.h> #include <Availability.h> /*! @header Lockless atomic enqueue and dequeue * These routines manipulate singly-linked LIFO lists. */ __BEGIN_DECLS /*! @abstract The data structure for a queue head. @discussion You should always initialize a queue head structure with the initialization vector {@link OS_ATOMIC_QUEUE_INIT} before use. */ #if defined(__x86_64__) typedef volatile struct { void *opaque1; long opaque2; } __attribute__ ((aligned (16))) OSQueueHead; #else typedef volatile struct { void *opaque1; long opaque2; } OSQueueHead; #endif /*! @abstract The initialization vector for a queue head. */ #define OS_ATOMIC_QUEUE_INIT { NULL, 0 } /*! @abstract Enqueue an element onto a list. @discussion Memory barriers are incorporated as needed to permit thread-safe access to the queue element. @param __list The list on which you want to enqueue the element. @param __new The element to add. @param __offset The "offset" parameter is the offset (in bytes) of the link field from the beginning of the data structure being queued (<code>__new</code>). The link field should be a pointer type. The <code>__offset</code> value needs to be same for all enqueuing and dequeuing operations on the same list, even if different structure types are enqueued on that list. The use of <code>offsetset()</code>, defined in <code>stddef.h</code> is the common way to specify the <code>__offset</code> value. */ __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_4_0) void OSAtomicEnqueue( OSQueueHead *__list, void *__new, size_t __offset); /*! @abstract Dequeue an element from a list. @discussion Memory barriers are incorporated as needed to permit thread-safe access to the queue element. @param __list The list from which you want to dequeue an element. @param __offset The "offset" parameter is the offset (in bytes) of the link field from the beginning of the data structure being dequeued (<code>__new</code>). The link field should be a pointer type. The <code>__offset</code> value needs to be same for all enqueuing and dequeuing operations on the same list, even if different structure types are enqueued on that list. The use of <code>offsetset()</code>, defined in <code>stddef.h</code> is the common way to specify the <code>__offset</code> value. IMPORTANT: the memory backing the link field of a queue element must not be unmapped after OSAtomicDequeue() returns until all concurrent calls to OSAtomicDequeue() for the same list on other threads have also returned, as they may still be accessing that memory location. @result Returns the most recently enqueued element, or <code>NULL</code> if the list is empty. */ __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_4_0) void* OSAtomicDequeue( OSQueueHead *__list, size_t __offset); #if defined(__x86_64__) || defined(__i386__) /*! @group Lockless atomic fifo enqueue and dequeue * These routines manipulate singly-linked FIFO lists. */ /*! @abstract The data structure for a fifo queue head. @discussion You should always initialize a fifo queue head structure with the initialization vector {@link OS_ATOMIC_FIFO_QUEUE_INIT} before use. */ #if defined(__x86_64__) typedef volatile struct { void *opaque1; void *opaque2; int opaque3; } __attribute__ ((aligned (16))) OSFifoQueueHead; #else typedef volatile struct { void *opaque1; void *opaque2; int opaque3; } OSFifoQueueHead; #endif /*! @abstract The initialization vector for a fifo queue head. */ #define OS_ATOMIC_FIFO_QUEUE_INIT { NULL, NULL, 0 } /*! @abstract Enqueue an element onto a list. @discussion Memory barriers are incorporated as needed to permit thread-safe access to the queue element. @param __list The list on which you want to enqueue the element. @param __new The element to add. @param __offset The "offset" parameter is the offset (in bytes) of the link field from the beginning of the data structure being queued (<code>__new</code>). The link field should be a pointer type. The <code>__offset</code> value needs to be same for all enqueuing and dequeuing operations on the same list, even if different structure types are enqueued on that list. The use of <code>offsetset()</code>, defined in <code>stddef.h</code> is the common way to specify the <code>__offset</code> value. */ __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA) void OSAtomicFifoEnqueue( OSFifoQueueHead *__list, void *__new, size_t __offset); /*! @abstract Dequeue an element from a list. @discussion Memory barriers are incorporated as needed to permit thread-safe access to the queue element. @param __list The list from which you want to dequeue an element. @param __offset The "offset" parameter is the offset (in bytes) of the link field from the beginning of the data structure being dequeued (<code>__new</code>). The link field should be a pointer type. The <code>__offset</code> value needs to be same for all enqueuing and dequeuing operations on the same list, even if different structure types are enqueued on that list. The use of <code>offsetset()</code>, defined in <code>stddef.h</code> is the common way to specify the <code>__offset</code> value. @result Returns the oldest enqueued element, or <code>NULL</code> if the list is empty. */ __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA) void* OSAtomicFifoDequeue( OSFifoQueueHead *__list, size_t __offset); #endif /* __i386__ || __x86_64__ */ __END_DECLS #endif /* _OSATOMICQUEUE_H_ */