diff options
Diffstat (limited to 'lib/libc/include/aarch64-macos-gnu/dispatch')
| -rw-r--r-- | lib/libc/include/aarch64-macos-gnu/dispatch/block.h | 428 | ||||
| -rw-r--r-- | lib/libc/include/aarch64-macos-gnu/dispatch/dispatch.h | 80 | ||||
| -rw-r--r-- | lib/libc/include/aarch64-macos-gnu/dispatch/group.h | 279 | ||||
| -rw-r--r-- | lib/libc/include/aarch64-macos-gnu/dispatch/object.h | 606 | ||||
| -rw-r--r-- | lib/libc/include/aarch64-macos-gnu/dispatch/queue.h | 1674 | ||||
| -rw-r--r-- | lib/libc/include/aarch64-macos-gnu/dispatch/semaphore.h | 117 | ||||
| -rw-r--r-- | lib/libc/include/aarch64-macos-gnu/dispatch/source.h | 780 | ||||
| -rw-r--r-- | lib/libc/include/aarch64-macos-gnu/dispatch/workloop.h | 163 |
8 files changed, 4127 insertions, 0 deletions
diff --git a/lib/libc/include/aarch64-macos-gnu/dispatch/block.h b/lib/libc/include/aarch64-macos-gnu/dispatch/block.h new file mode 100644 index 0000000000..f4b9b9ead4 --- /dev/null +++ b/lib/libc/include/aarch64-macos-gnu/dispatch/block.h @@ -0,0 +1,428 @@ +/* + * Copyright (c) 2014 Apple Inc. All rights reserved. + * + * @APPLE_APACHE_LICENSE_HEADER_START@ + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * @APPLE_APACHE_LICENSE_HEADER_END@ + */ + +#ifndef __DISPATCH_BLOCK__ +#define __DISPATCH_BLOCK__ + +#ifndef __DISPATCH_INDIRECT__ +#error "Please #include <dispatch/dispatch.h> instead of this file directly." +#include <dispatch/base.h> // for HeaderDoc +#endif + +#ifdef __BLOCKS__ + +/*! + * @group Dispatch block objects + */ + +DISPATCH_ASSUME_NONNULL_BEGIN + +__BEGIN_DECLS + +/*! + * @typedef dispatch_block_flags_t + * Flags to pass to the dispatch_block_create* functions. + * + * @const DISPATCH_BLOCK_BARRIER + * Flag indicating that a dispatch block object should act as a barrier block + * when submitted to a DISPATCH_QUEUE_CONCURRENT queue. + * See dispatch_barrier_async() for details. + * This flag has no effect when the dispatch block object is invoked directly. + * + * @const DISPATCH_BLOCK_DETACHED + * Flag indicating that a dispatch block object should execute disassociated + * from current execution context attributes such as os_activity_t + * and properties of the current IPC request (if any). With regard to QoS class, + * the behavior is the same as for DISPATCH_BLOCK_NO_QOS. If invoked directly, + * the block object will remove the other attributes from the calling thread for + * the duration of the block body (before applying attributes assigned to the + * block object, if any). If submitted to a queue, the block object will be + * executed with the attributes of the queue (or any attributes specifically + * assigned to the block object). + * + * @const DISPATCH_BLOCK_ASSIGN_CURRENT + * Flag indicating that a dispatch block object should be assigned the execution + * context attributes that are current at the time the block object is created. + * This applies to attributes such as QOS class, os_activity_t and properties of + * the current IPC request (if any). If invoked directly, the block object will + * apply these attributes to the calling thread for the duration of the block + * body. If the block object is submitted to a queue, this flag replaces the + * default behavior of associating the submitted block instance with the + * execution context attributes that are current at the time of submission. + * If a specific QOS class is assigned with DISPATCH_BLOCK_NO_QOS_CLASS or + * dispatch_block_create_with_qos_class(), that QOS class takes precedence over + * the QOS class assignment indicated by this flag. + * + * @const DISPATCH_BLOCK_NO_QOS_CLASS + * Flag indicating that a dispatch block object should be not be assigned a QOS + * class. If invoked directly, the block object will be executed with the QOS + * class of the calling thread. If the block object is submitted to a queue, + * this replaces the default behavior of associating the submitted block + * instance with the QOS class current at the time of submission. + * This flag is ignored if a specific QOS class is assigned with + * dispatch_block_create_with_qos_class(). + * + * @const DISPATCH_BLOCK_INHERIT_QOS_CLASS + * Flag indicating that execution of a dispatch block object submitted to a + * queue should prefer the QOS class assigned to the queue over the QOS class + * assigned to the block (resp. associated with the block at the time of + * submission). The latter will only be used if the queue in question does not + * have an assigned QOS class, as long as doing so does not result in a QOS + * class lower than the QOS class inherited from the queue's target queue. + * This flag is the default when a dispatch block object is submitted to a queue + * for asynchronous execution and has no effect when the dispatch block object + * is invoked directly. It is ignored if DISPATCH_BLOCK_ENFORCE_QOS_CLASS is + * also passed. + * + * @const DISPATCH_BLOCK_ENFORCE_QOS_CLASS + * Flag indicating that execution of a dispatch block object submitted to a + * queue should prefer the QOS class assigned to the block (resp. associated + * with the block at the time of submission) over the QOS class assigned to the + * queue, as long as doing so will not result in a lower QOS class. + * This flag is the default when a dispatch block object is submitted to a queue + * for synchronous execution or when the dispatch block object is invoked + * directly. + */ +DISPATCH_OPTIONS(dispatch_block_flags, unsigned long, + DISPATCH_BLOCK_BARRIER + DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x1, + DISPATCH_BLOCK_DETACHED + DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x2, + DISPATCH_BLOCK_ASSIGN_CURRENT + DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x4, + DISPATCH_BLOCK_NO_QOS_CLASS + DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x8, + DISPATCH_BLOCK_INHERIT_QOS_CLASS + DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x10, + DISPATCH_BLOCK_ENFORCE_QOS_CLASS + DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x20, +); + +/*! + * @function dispatch_block_create + * + * @abstract + * Create a new dispatch block object on the heap from an existing block and + * the given flags. + * + * @discussion + * The provided block is Block_copy'ed to the heap and retained by the newly + * created dispatch block object. + * + * The returned dispatch block object is intended to be submitted to a dispatch + * queue with dispatch_async() and related functions, but may also be invoked + * directly. Both operations can be performed an arbitrary number of times but + * only the first completed execution of a dispatch block object can be waited + * on with dispatch_block_wait() or observed with dispatch_block_notify(). + * + * If the returned dispatch block object is submitted to a dispatch queue, the + * submitted block instance will be associated with the QOS class current at the + * time of submission, unless one of the following flags assigned a specific QOS + * class (or no QOS class) at the time of block creation: + * - DISPATCH_BLOCK_ASSIGN_CURRENT + * - DISPATCH_BLOCK_NO_QOS_CLASS + * - DISPATCH_BLOCK_DETACHED + * The QOS class the block object will be executed with also depends on the QOS + * class assigned to the queue and which of the following flags was specified or + * defaulted to: + * - DISPATCH_BLOCK_INHERIT_QOS_CLASS (default for asynchronous execution) + * - DISPATCH_BLOCK_ENFORCE_QOS_CLASS (default for synchronous execution) + * See description of dispatch_block_flags_t for details. + * + * If the returned dispatch block object is submitted directly to a serial queue + * and is configured to execute with a specific QOS class, the system will make + * a best effort to apply the necessary QOS overrides to ensure that blocks + * submitted earlier to the serial queue are executed at that same QOS class or + * higher. + * + * @param flags + * Configuration flags for the block object. + * Passing a value that is not a bitwise OR of flags from dispatch_block_flags_t + * results in NULL being returned. + * + * @param block + * The block to create the dispatch block object from. + * + * @result + * The newly created dispatch block object, or NULL. + * When not building with Objective-C ARC, must be released with a -[release] + * message or the Block_release() function. + */ +API_AVAILABLE(macos(10.10), ios(8.0)) +DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_RETURNS_RETAINED_BLOCK +DISPATCH_WARN_RESULT DISPATCH_NOTHROW +dispatch_block_t +dispatch_block_create(dispatch_block_flags_t flags, dispatch_block_t block); + +/*! + * @function dispatch_block_create_with_qos_class + * + * @abstract + * Create a new dispatch block object on the heap from an existing block and + * the given flags, and assign it the specified QOS class and relative priority. + * + * @discussion + * The provided block is Block_copy'ed to the heap and retained by the newly + * created dispatch block object. + * + * The returned dispatch block object is intended to be submitted to a dispatch + * queue with dispatch_async() and related functions, but may also be invoked + * directly. Both operations can be performed an arbitrary number of times but + * only the first completed execution of a dispatch block object can be waited + * on with dispatch_block_wait() or observed with dispatch_block_notify(). + * + * If invoked directly, the returned dispatch block object will be executed with + * the assigned QOS class as long as that does not result in a lower QOS class + * than what is current on the calling thread. + * + * If the returned dispatch block object is submitted to a dispatch queue, the + * QOS class it will be executed with depends on the QOS class assigned to the + * block, the QOS class assigned to the queue and which of the following flags + * was specified or defaulted to: + * - DISPATCH_BLOCK_INHERIT_QOS_CLASS: default for asynchronous execution + * - DISPATCH_BLOCK_ENFORCE_QOS_CLASS: default for synchronous execution + * See description of dispatch_block_flags_t for details. + * + * If the returned dispatch block object is submitted directly to a serial queue + * and is configured to execute with a specific QOS class, the system will make + * a best effort to apply the necessary QOS overrides to ensure that blocks + * submitted earlier to the serial queue are executed at that same QOS class or + * higher. + * + * @param flags + * Configuration flags for the new block object. + * Passing a value that is not a bitwise OR of flags from dispatch_block_flags_t + * results in NULL being returned. + * + * @param qos_class + * A QOS class value: + * - QOS_CLASS_USER_INTERACTIVE + * - QOS_CLASS_USER_INITIATED + * - QOS_CLASS_DEFAULT + * - QOS_CLASS_UTILITY + * - QOS_CLASS_BACKGROUND + * - QOS_CLASS_UNSPECIFIED + * Passing QOS_CLASS_UNSPECIFIED is equivalent to specifying the + * DISPATCH_BLOCK_NO_QOS_CLASS flag. Passing any other value results in NULL + * being returned. + * + * @param relative_priority + * A relative priority within the QOS class. This value is a negative + * offset from the maximum supported scheduler priority for the given class. + * Passing a value greater than zero or less than QOS_MIN_RELATIVE_PRIORITY + * results in NULL being returned. + * + * @param block + * The block to create the dispatch block object from. + * + * @result + * The newly created dispatch block object, or NULL. + * When not building with Objective-C ARC, must be released with a -[release] + * message or the Block_release() function. + */ +API_AVAILABLE(macos(10.10), ios(8.0)) +DISPATCH_EXPORT DISPATCH_NONNULL4 DISPATCH_RETURNS_RETAINED_BLOCK +DISPATCH_WARN_RESULT DISPATCH_NOTHROW +dispatch_block_t +dispatch_block_create_with_qos_class(dispatch_block_flags_t flags, + dispatch_qos_class_t qos_class, int relative_priority, + dispatch_block_t block); + +/*! + * @function dispatch_block_perform + * + * @abstract + * Create, synchronously execute and release a dispatch block object from the + * specified block and flags. + * + * @discussion + * Behaves identically to the sequence + * <code> + * dispatch_block_t b = dispatch_block_create(flags, block); + * b(); + * Block_release(b); + * </code> + * but may be implemented more efficiently internally by not requiring a copy + * to the heap of the specified block or the allocation of a new block object. + * + * @param flags + * Configuration flags for the temporary block object. + * The result of passing a value that is not a bitwise OR of flags from + * dispatch_block_flags_t is undefined. + * + * @param block + * The block to create the temporary block object from. + */ +API_AVAILABLE(macos(10.10), ios(8.0)) +DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW +void +dispatch_block_perform(dispatch_block_flags_t flags, + DISPATCH_NOESCAPE dispatch_block_t block); + +/*! + * @function dispatch_block_wait + * + * @abstract + * Wait synchronously until execution of the specified dispatch block object has + * completed or until the specified timeout has elapsed. + * + * @discussion + * This function will return immediately if execution of the block object has + * already completed. + * + * It is not possible to wait for multiple executions of the same block object + * with this interface; use dispatch_group_wait() for that purpose. A single + * dispatch block object may either be waited on once and executed once, + * or it may be executed any number of times. The behavior of any other + * combination is undefined. Submission to a dispatch queue counts as an + * execution, even if cancellation (dispatch_block_cancel) means the block's + * code never runs. + * + * The result of calling this function from multiple threads simultaneously + * with the same dispatch block object is undefined, but note that doing so + * would violate the rules described in the previous paragraph. + * + * If this function returns indicating that the specified timeout has elapsed, + * then that invocation does not count as the one allowed wait. + * + * If at the time this function is called, the specified dispatch block object + * has been submitted directly to a serial queue, the system will make a best + * effort to apply the necessary QOS overrides to ensure that the block and any + * blocks submitted earlier to that serial queue are executed at the QOS class + * (or higher) of the thread calling dispatch_block_wait(). + * + * @param block + * The dispatch block object to wait on. + * The result of passing NULL or a block object not returned by one of the + * dispatch_block_create* functions is undefined. + * + * @param timeout + * When to timeout (see dispatch_time). As a convenience, there are the + * DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants. + * + * @result + * Returns zero on success (the dispatch block object completed within the + * specified timeout) or non-zero on error (i.e. timed out). + */ +API_AVAILABLE(macos(10.10), ios(8.0)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW +intptr_t +dispatch_block_wait(dispatch_block_t block, dispatch_time_t timeout); + +/*! + * @function dispatch_block_notify + * + * @abstract + * Schedule a notification block to be submitted to a queue when the execution + * of a specified dispatch block object has completed. + * + * @discussion + * This function will submit the notification block immediately if execution of + * the observed block object has already completed. + * + * It is not possible to be notified of multiple executions of the same block + * object with this interface, use dispatch_group_notify() for that purpose. + * + * A single dispatch block object may either be observed one or more times + * and executed once, or it may be executed any number of times. The behavior + * of any other combination is undefined. Submission to a dispatch queue + * counts as an execution, even if cancellation (dispatch_block_cancel) means + * the block's code never runs. + * + * If multiple notification blocks are scheduled for a single block object, + * there is no defined order in which the notification blocks will be submitted + * to their associated queues. + * + * @param block + * The dispatch block object to observe. + * The result of passing NULL or a block object not returned by one of the + * dispatch_block_create* functions is undefined. + * + * @param queue + * The queue to which the supplied notification block will be submitted when + * the observed block completes. + * + * @param notification_block + * The notification block to submit when the observed block object completes. + */ +API_AVAILABLE(macos(10.10), ios(8.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_block_notify(dispatch_block_t block, dispatch_queue_t queue, + dispatch_block_t notification_block); + +/*! + * @function dispatch_block_cancel + * + * @abstract + * Asynchronously cancel the specified dispatch block object. + * + * @discussion + * Cancellation causes any future execution of the dispatch block object to + * return immediately, but does not affect any execution of the block object + * that is already in progress. + * + * Release of any resources associated with the block object will be delayed + * until execution of the block object is next attempted (or any execution + * already in progress completes). + * + * NOTE: care needs to be taken to ensure that a block object that may be + * canceled does not capture any resources that require execution of the + * block body in order to be released (e.g. memory allocated with + * malloc(3) that the block body calls free(3) on). Such resources will + * be leaked if the block body is never executed due to cancellation. + * + * @param block + * The dispatch block object to cancel. + * The result of passing NULL or a block object not returned by one of the + * dispatch_block_create* functions is undefined. + */ +API_AVAILABLE(macos(10.10), ios(8.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_block_cancel(dispatch_block_t block); + +/*! + * @function dispatch_block_testcancel + * + * @abstract + * Tests whether the given dispatch block object has been canceled. + * + * @param block + * The dispatch block object to test. + * The result of passing NULL or a block object not returned by one of the + * dispatch_block_create* functions is undefined. + * + * @result + * Non-zero if canceled and zero if not canceled. + */ +API_AVAILABLE(macos(10.10), ios(8.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE +DISPATCH_NOTHROW +intptr_t +dispatch_block_testcancel(dispatch_block_t block); + +__END_DECLS + +DISPATCH_ASSUME_NONNULL_END + +#endif // __BLOCKS__ + +#endif // __DISPATCH_BLOCK__
\ No newline at end of file diff --git a/lib/libc/include/aarch64-macos-gnu/dispatch/dispatch.h b/lib/libc/include/aarch64-macos-gnu/dispatch/dispatch.h new file mode 100644 index 0000000000..34274a7a0f --- /dev/null +++ b/lib/libc/include/aarch64-macos-gnu/dispatch/dispatch.h @@ -0,0 +1,80 @@ +/* + * Copyright (c) 2008-2013 Apple Inc. All rights reserved. + * + * @APPLE_APACHE_LICENSE_HEADER_START@ + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * @APPLE_APACHE_LICENSE_HEADER_END@ + */ + +#ifndef __DISPATCH_PUBLIC__ +#define __DISPATCH_PUBLIC__ + +#ifdef __APPLE__ +#include <Availability.h> +#include <os/availability.h> +#include <TargetConditionals.h> +#include <os/base.h> +#elif defined(_WIN32) +#include <os/generic_win_base.h> +#elif defined(__unix__) +#include <os/generic_unix_base.h> +#endif + +#include <sys/types.h> +#include <stddef.h> +#include <stdint.h> +#include <stdbool.h> +#include <stdarg.h> +#include <string.h> +#if defined(__unix__) || (defined(__APPLE__) && defined(__MACH__)) +#include <unistd.h> +#endif +#include <fcntl.h> +#if defined(_WIN32) +#include <time.h> +#endif + +#if (defined(__linux__) || defined(__FreeBSD__)) && defined(__has_feature) +#if __has_feature(modules) +#if !defined(__arm__) +#include <stdio.h> // for off_t (to match Glibc.modulemap) +#endif +#endif +#endif + +#define DISPATCH_API_VERSION 20181008 + +#ifndef __DISPATCH_INDIRECT__ +#define __DISPATCH_INDIRECT__ +#endif + +#include <os/object.h> +#include <os/workgroup.h> +#include <dispatch/base.h> +#include <dispatch/time.h> +#include <dispatch/object.h> +#include <dispatch/queue.h> +#include <dispatch/block.h> +#include <dispatch/source.h> +#include <dispatch/group.h> +#include <dispatch/semaphore.h> +#include <dispatch/once.h> +#include <dispatch/data.h> +#include <dispatch/io.h> +#include <dispatch/workloop.h> + +#undef __DISPATCH_INDIRECT__ + +#endif
\ No newline at end of file diff --git a/lib/libc/include/aarch64-macos-gnu/dispatch/group.h b/lib/libc/include/aarch64-macos-gnu/dispatch/group.h new file mode 100644 index 0000000000..549da4b3fc --- /dev/null +++ b/lib/libc/include/aarch64-macos-gnu/dispatch/group.h @@ -0,0 +1,279 @@ +/* + * Copyright (c) 2008-2013 Apple Inc. All rights reserved. + * + * @APPLE_APACHE_LICENSE_HEADER_START@ + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * @APPLE_APACHE_LICENSE_HEADER_END@ + */ + +#ifndef __DISPATCH_GROUP__ +#define __DISPATCH_GROUP__ + +#ifndef __DISPATCH_INDIRECT__ +#error "Please #include <dispatch/dispatch.h> instead of this file directly." +#include <dispatch/base.h> // for HeaderDoc +#endif + +DISPATCH_ASSUME_NONNULL_BEGIN + +/*! + * @typedef dispatch_group_t + * @abstract + * A group of blocks submitted to queues for asynchronous invocation. + */ +DISPATCH_DECL(dispatch_group); + +__BEGIN_DECLS + +/*! + * @function dispatch_group_create + * + * @abstract + * Creates new group with which blocks may be associated. + * + * @discussion + * This function creates a new group with which blocks may be associated. + * The dispatch group may be used to wait for the completion of the blocks it + * references. The group object memory is freed with dispatch_release(). + * + * @result + * The newly created group, or NULL on failure. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT +DISPATCH_NOTHROW +dispatch_group_t +dispatch_group_create(void); + +/*! + * @function dispatch_group_async + * + * @abstract + * Submits a block to a dispatch queue and associates the block with the given + * dispatch group. + * + * @discussion + * Submits a block to a dispatch queue and associates the block with the given + * dispatch group. The dispatch group may be used to wait for the completion + * of the blocks it references. + * + * @param group + * A dispatch group to associate with the submitted block. + * The result of passing NULL in this parameter is undefined. + * + * @param queue + * The dispatch queue to which the block will be submitted for asynchronous + * invocation. + * + * @param block + * The block to perform asynchronously. + */ +#ifdef __BLOCKS__ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_group_async(dispatch_group_t group, + dispatch_queue_t queue, + dispatch_block_t block); +#endif /* __BLOCKS__ */ + +/*! + * @function dispatch_group_async_f + * + * @abstract + * Submits a function to a dispatch queue and associates the block with the + * given dispatch group. + * + * @discussion + * See dispatch_group_async() for details. + * + * @param group + * A dispatch group to associate with the submitted function. + * The result of passing NULL in this parameter is undefined. + * + * @param queue + * The dispatch queue to which the function will be submitted for asynchronous + * invocation. + * + * @param context + * The application-defined context parameter to pass to the function. + * + * @param work + * The application-defined function to invoke on the target queue. The first + * parameter passed to this function is the context provided to + * dispatch_group_async_f(). + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4 +DISPATCH_NOTHROW +void +dispatch_group_async_f(dispatch_group_t group, + dispatch_queue_t queue, + void *_Nullable context, + dispatch_function_t work); + +/*! + * @function dispatch_group_wait + * + * @abstract + * Wait synchronously until all the blocks associated with a group have + * completed or until the specified timeout has elapsed. + * + * @discussion + * This function waits for the completion of the blocks associated with the + * given dispatch group, and returns after all blocks have completed or when + * the specified timeout has elapsed. + * + * This function will return immediately if there are no blocks associated + * with the dispatch group (i.e. the group is empty). + * + * The result of calling this function from multiple threads simultaneously + * with the same dispatch group is undefined. + * + * After the successful return of this function, the dispatch group is empty. + * It may either be released with dispatch_release() or re-used for additional + * blocks. See dispatch_group_async() for more information. + * + * @param group + * The dispatch group to wait on. + * The result of passing NULL in this parameter is undefined. + * + * @param timeout + * When to timeout (see dispatch_time). As a convenience, there are the + * DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants. + * + * @result + * Returns zero on success (all blocks associated with the group completed + * within the specified timeout) or non-zero on error (i.e. timed out). + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +intptr_t +dispatch_group_wait(dispatch_group_t group, dispatch_time_t timeout); + +/*! + * @function dispatch_group_notify + * + * @abstract + * Schedule a block to be submitted to a queue when all the blocks associated + * with a group have completed. + * + * @discussion + * This function schedules a notification block to be submitted to the specified + * queue once all blocks associated with the dispatch group have completed. + * + * If no blocks are associated with the dispatch group (i.e. the group is empty) + * then the notification block will be submitted immediately. + * + * The group will be empty at the time the notification block is submitted to + * the target queue. The group may either be released with dispatch_release() + * or reused for additional operations. + * See dispatch_group_async() for more information. + * + * @param group + * The dispatch group to observe. + * The result of passing NULL in this parameter is undefined. + * + * @param queue + * The queue to which the supplied block will be submitted when the group + * completes. + * + * @param block + * The block to submit when the group completes. + */ +#ifdef __BLOCKS__ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_group_notify(dispatch_group_t group, + dispatch_queue_t queue, + dispatch_block_t block); +#endif /* __BLOCKS__ */ + +/*! + * @function dispatch_group_notify_f + * + * @abstract + * Schedule a function to be submitted to a queue when all the blocks + * associated with a group have completed. + * + * @discussion + * See dispatch_group_notify() for details. + * + * @param group + * The dispatch group to observe. + * The result of passing NULL in this parameter is undefined. + * + * @param context + * The application-defined context parameter to pass to the function. + * + * @param work + * The application-defined function to invoke on the target queue. The first + * parameter passed to this function is the context provided to + * dispatch_group_notify_f(). + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4 +DISPATCH_NOTHROW +void +dispatch_group_notify_f(dispatch_group_t group, + dispatch_queue_t queue, + void *_Nullable context, + dispatch_function_t work); + +/*! + * @function dispatch_group_enter + * + * @abstract + * Manually indicate a block has entered the group + * + * @discussion + * Calling this function indicates another block has joined the group through + * a means other than dispatch_group_async(). Calls to this function must be + * balanced with dispatch_group_leave(). + * + * @param group + * The dispatch group to update. + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_group_enter(dispatch_group_t group); + +/*! + * @function dispatch_group_leave + * + * @abstract + * Manually indicate a block in the group has completed + * + * @discussion + * Calling this function indicates block has completed and left the dispatch + * group by a means other than dispatch_group_async(). + * + * @param group + * The dispatch group to update. + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_group_leave(dispatch_group_t group); + +__END_DECLS + +DISPATCH_ASSUME_NONNULL_END + +#endif
\ No newline at end of file diff --git a/lib/libc/include/aarch64-macos-gnu/dispatch/object.h b/lib/libc/include/aarch64-macos-gnu/dispatch/object.h new file mode 100644 index 0000000000..c658773f09 --- /dev/null +++ b/lib/libc/include/aarch64-macos-gnu/dispatch/object.h @@ -0,0 +1,606 @@ +/* + * Copyright (c) 2008-2012 Apple Inc. All rights reserved. + * + * @APPLE_APACHE_LICENSE_HEADER_START@ + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * @APPLE_APACHE_LICENSE_HEADER_END@ + */ + +#ifndef __DISPATCH_OBJECT__ +#define __DISPATCH_OBJECT__ + +#ifndef __DISPATCH_INDIRECT__ +#error "Please #include <dispatch/dispatch.h> instead of this file directly." +#include <dispatch/base.h> // for HeaderDoc +#endif + +#if __has_include(<sys/qos.h>) +#include <sys/qos.h> +#endif + +DISPATCH_ASSUME_NONNULL_BEGIN + +/*! + * @typedef dispatch_object_t + * + * @abstract + * Abstract base type for all dispatch objects. + * The details of the type definition are language-specific. + * + * @discussion + * Dispatch objects are reference counted via calls to dispatch_retain() and + * dispatch_release(). + */ + +#if OS_OBJECT_USE_OBJC +/* + * By default, dispatch objects are declared as Objective-C types when building + * with an Objective-C compiler. This allows them to participate in ARC, in RR + * management by the Blocks runtime and in leaks checking by the static + * analyzer, and enables them to be added to Cocoa collections. + * See <os/object.h> for details. + */ +OS_OBJECT_DECL_CLASS(dispatch_object); + +#if OS_OBJECT_SWIFT3 +#define DISPATCH_DECL(name) OS_OBJECT_DECL_SUBCLASS_SWIFT(name, dispatch_object) +#define DISPATCH_DECL_SUBCLASS(name, base) OS_OBJECT_DECL_SUBCLASS_SWIFT(name, base) +#else // OS_OBJECT_SWIFT3 +#define DISPATCH_DECL(name) OS_OBJECT_DECL_SUBCLASS(name, dispatch_object) +#define DISPATCH_DECL_SUBCLASS(name, base) OS_OBJECT_DECL_SUBCLASS(name, base) + +DISPATCH_INLINE DISPATCH_ALWAYS_INLINE DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +_dispatch_object_validate(dispatch_object_t object) +{ + void *isa = *(void *volatile*)(OS_OBJECT_BRIDGE void*)object; + (void)isa; +} +#endif // OS_OBJECT_SWIFT3 + +#define DISPATCH_GLOBAL_OBJECT(type, object) ((OS_OBJECT_BRIDGE type)&(object)) +#define DISPATCH_RETURNS_RETAINED OS_OBJECT_RETURNS_RETAINED +#elif defined(__cplusplus) && !defined(__DISPATCH_BUILDING_DISPATCH__) +/* + * Dispatch objects are NOT C++ objects. Nevertheless, we can at least keep C++ + * aware of type compatibility. + */ +typedef struct dispatch_object_s { +private: + dispatch_object_s(); + ~dispatch_object_s(); + dispatch_object_s(const dispatch_object_s &); + void operator=(const dispatch_object_s &); +} *dispatch_object_t; +#define DISPATCH_DECL(name) \ + typedef struct name##_s : public dispatch_object_s {} *name##_t +#define DISPATCH_DECL_SUBCLASS(name, base) \ + typedef struct name##_s : public base##_s {} *name##_t +#define DISPATCH_GLOBAL_OBJECT(type, object) (static_cast<type>(&(object))) +#define DISPATCH_RETURNS_RETAINED +#else /* Plain C */ +typedef union { + struct _os_object_s *_os_obj; + struct dispatch_object_s *_do; + struct dispatch_queue_s *_dq; + struct dispatch_queue_attr_s *_dqa; + struct dispatch_group_s *_dg; + struct dispatch_source_s *_ds; + struct dispatch_channel_s *_dch; + struct dispatch_mach_s *_dm; + struct dispatch_mach_msg_s *_dmsg; + struct dispatch_semaphore_s *_dsema; + struct dispatch_data_s *_ddata; + struct dispatch_io_s *_dchannel; +} dispatch_object_t DISPATCH_TRANSPARENT_UNION; +#define DISPATCH_DECL(name) typedef struct name##_s *name##_t +#define DISPATCH_DECL_SUBCLASS(name, base) typedef base##_t name##_t +#define DISPATCH_GLOBAL_OBJECT(type, object) ((type)&(object)) +#define DISPATCH_RETURNS_RETAINED +#endif + +#if OS_OBJECT_SWIFT3 && OS_OBJECT_USE_OBJC +#define DISPATCH_SOURCE_TYPE_DECL(name) \ + DISPATCH_EXPORT struct dispatch_source_type_s \ + _dispatch_source_type_##name; \ + OS_OBJECT_DECL_PROTOCOL(dispatch_source_##name, <OS_dispatch_source>); \ + OS_OBJECT_CLASS_IMPLEMENTS_PROTOCOL( \ + dispatch_source, dispatch_source_##name) +#define DISPATCH_SOURCE_DECL(name) \ + DISPATCH_DECL(name); \ + OS_OBJECT_DECL_PROTOCOL(name, <NSObject>); \ + OS_OBJECT_CLASS_IMPLEMENTS_PROTOCOL(name, name) +#ifndef DISPATCH_DATA_DECL +#define DISPATCH_DATA_DECL(name) OS_OBJECT_DECL_SWIFT(name) +#endif // DISPATCH_DATA_DECL +#else +#define DISPATCH_SOURCE_DECL(name) \ + DISPATCH_DECL(name); +#define DISPATCH_DATA_DECL(name) DISPATCH_DECL(name) +#define DISPATCH_SOURCE_TYPE_DECL(name) \ + DISPATCH_EXPORT const struct dispatch_source_type_s \ + _dispatch_source_type_##name +#endif + +#ifdef __BLOCKS__ +/*! + * @typedef dispatch_block_t + * + * @abstract + * The type of blocks submitted to dispatch queues, which take no arguments + * and have no return value. + * + * @discussion + * When not building with Objective-C ARC, a block object allocated on or + * copied to the heap must be released with a -[release] message or the + * Block_release() function. + * + * The declaration of a block literal allocates storage on the stack. + * Therefore, this is an invalid construct: + * <code> + * dispatch_block_t block; + * if (x) { + * block = ^{ printf("true\n"); }; + * } else { + * block = ^{ printf("false\n"); }; + * } + * block(); // unsafe!!! + * </code> + * + * What is happening behind the scenes: + * <code> + * if (x) { + * struct Block __tmp_1 = ...; // setup details + * block = &__tmp_1; + * } else { + * struct Block __tmp_2 = ...; // setup details + * block = &__tmp_2; + * } + * </code> + * + * As the example demonstrates, the address of a stack variable is escaping the + * scope in which it is allocated. That is a classic C bug. + * + * Instead, the block literal must be copied to the heap with the Block_copy() + * function or by sending it a -[copy] message. + */ +typedef void (^dispatch_block_t)(void); +#endif // __BLOCKS__ + +__BEGIN_DECLS + +/*! + * @typedef dispatch_qos_class_t + * Alias for qos_class_t type. + */ +#if __has_include(<sys/qos.h>) +typedef qos_class_t dispatch_qos_class_t; +#else +typedef unsigned int dispatch_qos_class_t; +#endif + +/*! + * @function dispatch_retain + * + * @abstract + * Increment the reference count of a dispatch object. + * + * @discussion + * Calls to dispatch_retain() must be balanced with calls to + * dispatch_release(). + * + * @param object + * The object to retain. + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +DISPATCH_SWIFT_UNAVAILABLE("Can't be used with ARC") +void +dispatch_retain(dispatch_object_t object); +#if OS_OBJECT_USE_OBJC_RETAIN_RELEASE +#undef dispatch_retain +#define dispatch_retain(object) \ + __extension__({ dispatch_object_t _o = (object); \ + _dispatch_object_validate(_o); (void)[_o retain]; }) +#endif + +/*! + * @function dispatch_release + * + * @abstract + * Decrement the reference count of a dispatch object. + * + * @discussion + * A dispatch object is asynchronously deallocated once all references are + * released (i.e. the reference count becomes zero). The system does not + * guarantee that a given client is the last or only reference to a given + * object. + * + * @param object + * The object to release. + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +DISPATCH_SWIFT_UNAVAILABLE("Can't be used with ARC") +void +dispatch_release(dispatch_object_t object); +#if OS_OBJECT_USE_OBJC_RETAIN_RELEASE +#undef dispatch_release +#define dispatch_release(object) \ + __extension__({ dispatch_object_t _o = (object); \ + _dispatch_object_validate(_o); [_o release]; }) +#endif + +/*! + * @function dispatch_get_context + * + * @abstract + * Returns the application defined context of the object. + * + * @param object + * The result of passing NULL in this parameter is undefined. + * + * @result + * The context of the object; may be NULL. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT +DISPATCH_NOTHROW +void *_Nullable +dispatch_get_context(dispatch_object_t object); + +/*! + * @function dispatch_set_context + * + * @abstract + * Associates an application defined context with the object. + * + * @param object + * The result of passing NULL in this parameter is undefined. + * + * @param context + * The new client defined context for the object. This may be NULL. + * + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NOTHROW +void +dispatch_set_context(dispatch_object_t object, void *_Nullable context); + +/*! + * @function dispatch_set_finalizer_f + * + * @abstract + * Set the finalizer function for a dispatch object. + * + * @param object + * The dispatch object to modify. + * The result of passing NULL in this parameter is undefined. + * + * @param finalizer + * The finalizer function pointer. + * + * @discussion + * A dispatch object's finalizer will be invoked on the object's target queue + * after all references to the object have been released. This finalizer may be + * used by the application to release any resources associated with the object, + * such as freeing the object's context. + * The context parameter passed to the finalizer function is the current + * context of the dispatch object at the time the finalizer call is made. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NOTHROW +void +dispatch_set_finalizer_f(dispatch_object_t object, + dispatch_function_t _Nullable finalizer); + +/*! + * @function dispatch_activate + * + * @abstract + * Activates the specified dispatch object. + * + * @discussion + * Dispatch objects such as queues and sources may be created in an inactive + * state. Objects in this state have to be activated before any blocks + * associated with them will be invoked. + * + * The target queue of inactive objects can be changed using + * dispatch_set_target_queue(). Change of target queue is no longer permitted + * once an initially inactive object has been activated. + * + * Calling dispatch_activate() on an active object has no effect. + * Releasing the last reference count on an inactive object is undefined. + * + * @param object + * The object to be activated. + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_activate(dispatch_object_t object); + +/*! + * @function dispatch_suspend + * + * @abstract + * Suspends the invocation of blocks on a dispatch object. + * + * @discussion + * A suspended object will not invoke any blocks associated with it. The + * suspension of an object will occur after any running block associated with + * the object completes. + * + * Calls to dispatch_suspend() must be balanced with calls + * to dispatch_resume(). + * + * @param object + * The object to be suspended. + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_suspend(dispatch_object_t object); + +/*! + * @function dispatch_resume + * + * @abstract + * Resumes the invocation of blocks on a dispatch object. + * + * @discussion + * Dispatch objects can be suspended with dispatch_suspend(), which increments + * an internal suspension count. dispatch_resume() is the inverse operation, + * and consumes suspension counts. When the last suspension count is consumed, + * blocks associated with the object will be invoked again. + * + * For backward compatibility reasons, dispatch_resume() on an inactive and not + * otherwise suspended dispatch source object has the same effect as calling + * dispatch_activate(). For new code, using dispatch_activate() is preferred. + * + * If the specified object has zero suspension count and is not an inactive + * source, this function will result in an assertion and the process being + * terminated. + * + * @param object + * The object to be resumed. + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_resume(dispatch_object_t object); + +/*! + * @function dispatch_set_qos_class_floor + * + * @abstract + * Sets the QOS class floor on a dispatch queue, source or workloop. + * + * @discussion + * The QOS class of workitems submitted to this object asynchronously will be + * elevated to at least the specified QOS class floor. The QOS of the workitem + * will be used if higher than the floor even when the workitem has been created + * without "ENFORCE" semantics. + * + * Setting the QOS class floor is equivalent to the QOS effects of configuring + * a queue whose target queue has a QoS class set to the same value. + * + * @param object + * A dispatch queue, workloop, or source to configure. + * The object must be inactive. + * + * Passing another object type or an object that has been activated is undefined + * and will cause the process to be terminated. + * + * @param qos_class + * A QOS class value: + * - QOS_CLASS_USER_INTERACTIVE + * - QOS_CLASS_USER_INITIATED + * - QOS_CLASS_DEFAULT + * - QOS_CLASS_UTILITY + * - QOS_CLASS_BACKGROUND + * Passing any other value is undefined. + * + * @param relative_priority + * A relative priority within the QOS class. This value is a negative + * offset from the maximum supported scheduler priority for the given class. + * Passing a value greater than zero or less than QOS_MIN_RELATIVE_PRIORITY + * is undefined. + */ +API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) +DISPATCH_EXPORT DISPATCH_NOTHROW +void +dispatch_set_qos_class_floor(dispatch_object_t object, + dispatch_qos_class_t qos_class, int relative_priority); + +#ifdef __BLOCKS__ +/*! + * @function dispatch_wait + * + * @abstract + * Wait synchronously for an object or until the specified timeout has elapsed. + * + * @discussion + * Type-generic macro that maps to dispatch_block_wait, dispatch_group_wait or + * dispatch_semaphore_wait, depending on the type of the first argument. + * See documentation for these functions for more details. + * This function is unavailable for any other object type. + * + * @param object + * The object to wait on. + * The result of passing NULL in this parameter is undefined. + * + * @param timeout + * When to timeout (see dispatch_time). As a convenience, there are the + * DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants. + * + * @result + * Returns zero on success or non-zero on error (i.e. timed out). + */ +DISPATCH_UNAVAILABLE +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW +intptr_t +dispatch_wait(void *object, dispatch_time_t timeout); +#if __has_extension(c_generic_selections) +#define dispatch_wait(object, timeout) \ + _Generic((object), \ + dispatch_block_t:dispatch_block_wait, \ + dispatch_group_t:dispatch_group_wait, \ + dispatch_semaphore_t:dispatch_semaphore_wait \ + )((object),(timeout)) +#endif + +/*! + * @function dispatch_notify + * + * @abstract + * Schedule a notification block to be submitted to a queue when the execution + * of a specified object has completed. + * + * @discussion + * Type-generic macro that maps to dispatch_block_notify or + * dispatch_group_notify, depending on the type of the first argument. + * See documentation for these functions for more details. + * This function is unavailable for any other object type. + * + * @param object + * The object to observe. + * The result of passing NULL in this parameter is undefined. + * + * @param queue + * The queue to which the supplied notification block will be submitted when + * the observed object completes. + * + * @param notification_block + * The block to submit when the observed object completes. + */ +DISPATCH_UNAVAILABLE +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_notify(void *object, dispatch_object_t queue, + dispatch_block_t notification_block); +#if __has_extension(c_generic_selections) +#define dispatch_notify(object, queue, notification_block) \ + _Generic((object), \ + dispatch_block_t:dispatch_block_notify, \ + dispatch_group_t:dispatch_group_notify \ + )((object),(queue), (notification_block)) +#endif + +/*! + * @function dispatch_cancel + * + * @abstract + * Cancel the specified object. + * + * @discussion + * Type-generic macro that maps to dispatch_block_cancel or + * dispatch_source_cancel, depending on the type of the first argument. + * See documentation for these functions for more details. + * This function is unavailable for any other object type. + * + * @param object + * The object to cancel. + * The result of passing NULL in this parameter is undefined. + */ +DISPATCH_UNAVAILABLE +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_cancel(void *object); +#if __has_extension(c_generic_selections) +#define dispatch_cancel(object) \ + _Generic((object), \ + dispatch_block_t:dispatch_block_cancel, \ + dispatch_source_t:dispatch_source_cancel \ + )((object)) +#endif + +/*! + * @function dispatch_testcancel + * + * @abstract + * Test whether the specified object has been canceled + * + * @discussion + * Type-generic macro that maps to dispatch_block_testcancel or + * dispatch_source_testcancel, depending on the type of the first argument. + * See documentation for these functions for more details. + * This function is unavailable for any other object type. + * + * @param object + * The object to test. + * The result of passing NULL in this parameter is undefined. + * + * @result + * Non-zero if canceled and zero if not canceled. + */ +DISPATCH_UNAVAILABLE +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE +DISPATCH_NOTHROW +intptr_t +dispatch_testcancel(void *object); +#if __has_extension(c_generic_selections) +#define dispatch_testcancel(object) \ + _Generic((object), \ + dispatch_block_t:dispatch_block_testcancel, \ + dispatch_source_t:dispatch_source_testcancel \ + )((object)) +#endif +#endif // __BLOCKS__ + +/*! + * @function dispatch_debug + * + * @abstract + * Programmatically log debug information about a dispatch object. + * + * @discussion + * Programmatically log debug information about a dispatch object. By default, + * the log output is sent to syslog at notice level. In the debug version of + * the library, the log output is sent to a file in /var/tmp. + * The log output destination can be configured via the LIBDISPATCH_LOG + * environment variable, valid values are: YES, NO, syslog, stderr, file. + * + * This function is deprecated and will be removed in a future release. + * Objective-C callers may use -debugDescription instead. + * + * @param object + * The object to introspect. + * + * @param message + * The message to log above and beyond the introspection. + */ +API_DEPRECATED("unsupported interface", macos(10.6,10.9), ios(4.0,6.0)) +DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW DISPATCH_COLD +__attribute__((__format__(printf,2,3))) +void +dispatch_debug(dispatch_object_t object, const char *message, ...); + +API_DEPRECATED("unsupported interface", macos(10.6,10.9), ios(4.0,6.0)) +DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW DISPATCH_COLD +__attribute__((__format__(printf,2,0))) +void +dispatch_debugv(dispatch_object_t object, const char *message, va_list ap); + +__END_DECLS + +DISPATCH_ASSUME_NONNULL_END + +#endif
\ No newline at end of file diff --git a/lib/libc/include/aarch64-macos-gnu/dispatch/queue.h b/lib/libc/include/aarch64-macos-gnu/dispatch/queue.h new file mode 100644 index 0000000000..f4f8ab673e --- /dev/null +++ b/lib/libc/include/aarch64-macos-gnu/dispatch/queue.h @@ -0,0 +1,1674 @@ +/* + * Copyright (c) 2008-2014 Apple Inc. All rights reserved. + * + * @APPLE_APACHE_LICENSE_HEADER_START@ + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * @APPLE_APACHE_LICENSE_HEADER_END@ + */ + +#ifndef __DISPATCH_QUEUE__ +#define __DISPATCH_QUEUE__ + +#ifndef __DISPATCH_INDIRECT__ +#error "Please #include <dispatch/dispatch.h> instead of this file directly." +#include <dispatch/base.h> // for HeaderDoc +#endif + +DISPATCH_ASSUME_NONNULL_BEGIN + +/*! + * @header + * + * Dispatch is an abstract model for expressing concurrency via simple but + * powerful API. + * + * At the core, dispatch provides serial FIFO queues to which blocks may be + * submitted. Blocks submitted to these dispatch queues are invoked on a pool + * of threads fully managed by the system. No guarantee is made regarding + * which thread a block will be invoked on; however, it is guaranteed that only + * one block submitted to the FIFO dispatch queue will be invoked at a time. + * + * When multiple queues have blocks to be processed, the system is free to + * allocate additional threads to invoke the blocks concurrently. When the + * queues become empty, these threads are automatically released. + */ + +/*! + * @typedef dispatch_queue_t + * + * @abstract + * Dispatch queues invoke workitems submitted to them. + * + * @discussion + * Dispatch queues come in many flavors, the most common one being the dispatch + * serial queue (See dispatch_queue_serial_t). + * + * The system manages a pool of threads which process dispatch queues and invoke + * workitems submitted to them. + * + * Conceptually a dispatch queue may have its own thread of execution, and + * interaction between queues is highly asynchronous. + * + * Dispatch queues are reference counted via calls to dispatch_retain() and + * dispatch_release(). Pending workitems submitted to a queue also hold a + * reference to the queue until they have finished. Once all references to a + * queue have been released, the queue will be deallocated by the system. + */ +DISPATCH_DECL(dispatch_queue); + +/*! + * @typedef dispatch_queue_global_t + * + * @abstract + * Dispatch global concurrent queues are an abstraction around the system thread + * pool which invokes workitems that are submitted to dispatch queues. + * + * @discussion + * Dispatch global concurrent queues provide buckets of priorities on top of the + * thread pool the system manages. The system will decide how many threads + * to allocate to this pool depending on demand and system load. In particular, + * the system tries to maintain a good level of concurrency for this resource, + * and will create new threads when too many existing worker threads block in + * system calls. + * + * The global concurrent queues are a shared resource and as such it is the + * responsiblity of every user of this resource to not submit an unbounded + * amount of work to this pool, especially work that may block, as this can + * cause the system to spawn very large numbers of threads (aka. thread + * explosion). + * + * Work items submitted to the global concurrent queues have no ordering + * guarantee with respect to the order of submission, and workitems submitted + * to these queues may be invoked concurrently. + * + * Dispatch global concurrent queues are well-known global objects that are + * returned by dispatch_get_global_queue(). These objects cannot be modified. + * Calls to dispatch_suspend(), dispatch_resume(), dispatch_set_context(), etc., + * will have no effect when used with queues of this type. + */ +DISPATCH_DECL_SUBCLASS(dispatch_queue_global, dispatch_queue); + +/*! + * @typedef dispatch_queue_serial_t + * + * @abstract + * Dispatch serial queues invoke workitems submitted to them serially in FIFO + * order. + * + * @discussion + * Dispatch serial queues are lightweight objects to which workitems may be + * submitted to be invoked in FIFO order. A serial queue will only invoke one + * workitem at a time, but independent serial queues may each invoke their work + * items concurrently with respect to each other. + * + * Serial queues can target each other (See dispatch_set_target_queue()). The + * serial queue at the bottom of a queue hierarchy provides an exclusion + * context: at most one workitem submitted to any of the queues in such + * a hiearchy will run at any given time. + * + * Such hierarchies provide a natural construct to organize an application + * subsystem around. + * + * Serial queues are created by passing a dispatch queue attribute derived from + * DISPATCH_QUEUE_SERIAL to dispatch_queue_create_with_target(). + */ +DISPATCH_DECL_SUBCLASS(dispatch_queue_serial, dispatch_queue); + +/*! + * @typedef dispatch_queue_main_t + * + * @abstract + * The type of the default queue that is bound to the main thread. + * + * @discussion + * The main queue is a serial queue (See dispatch_queue_serial_t) which is bound + * to the main thread of an application. + * + * In order to invoke workitems submitted to the main queue, the application + * must call dispatch_main(), NSApplicationMain(), or use a CFRunLoop on the + * main thread. + * + * The main queue is a well known global object that is made automatically on + * behalf of the main thread during process initialization and is returned by + * dispatch_get_main_queue(). This object cannot be modified. Calls to + * dispatch_suspend(), dispatch_resume(), dispatch_set_context(), etc., will + * have no effect when used on the main queue. + */ +DISPATCH_DECL_SUBCLASS(dispatch_queue_main, dispatch_queue_serial); + +/*! + * @typedef dispatch_queue_concurrent_t + * + * @abstract + * Dispatch concurrent queues invoke workitems submitted to them concurrently, + * and admit a notion of barrier workitems. + * + * @discussion + * Dispatch concurrent queues are lightweight objects to which regular and + * barrier workitems may be submited. Barrier workitems are invoked in + * exclusion of any other kind of workitem in FIFO order. + * + * Regular workitems can be invoked concurrently for the same concurrent queue, + * in any order. However, regular workitems will not be invoked before any + * barrier workitem submited ahead of them has been invoked. + * + * In other words, if a serial queue is equivalent to a mutex in the Dispatch + * world, a concurrent queue is equivalent to a reader-writer lock, where + * regular items are readers and barriers are writers. + * + * Concurrent queues are created by passing a dispatch queue attribute derived + * from DISPATCH_QUEUE_CONCURRENT to dispatch_queue_create_with_target(). + * + * Caveat: + * Dispatch concurrent queues at this time do not implement priority inversion + * avoidance when lower priority regular workitems (readers) are being invoked + * and are preventing a higher priority barrier (writer) from being invoked. + */ +DISPATCH_DECL_SUBCLASS(dispatch_queue_concurrent, dispatch_queue); + +__BEGIN_DECLS + +/*! + * @function dispatch_async + * + * @abstract + * Submits a block for asynchronous execution on a dispatch queue. + * + * @discussion + * The dispatch_async() function is the fundamental mechanism for submitting + * blocks to a dispatch queue. + * + * Calls to dispatch_async() always return immediately after the block has + * been submitted, and never wait for the block to be invoked. + * + * The target queue determines whether the block will be invoked serially or + * concurrently with respect to other blocks submitted to that same queue. + * Serial queues are processed concurrently with respect to each other. + * + * @param queue + * The target dispatch queue to which the block is submitted. + * The system will hold a reference on the target queue until the block + * has finished. + * The result of passing NULL in this parameter is undefined. + * + * @param block + * The block to submit to the target dispatch queue. This function performs + * Block_copy() and Block_release() on behalf of callers. + * The result of passing NULL in this parameter is undefined. + */ +#ifdef __BLOCKS__ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_async(dispatch_queue_t queue, dispatch_block_t block); +#endif + +/*! + * @function dispatch_async_f + * + * @abstract + * Submits a function for asynchronous execution on a dispatch queue. + * + * @discussion + * See dispatch_async() for details. + * + * @param queue + * The target dispatch queue to which the function is submitted. + * The system will hold a reference on the target queue until the function + * has returned. + * The result of passing NULL in this parameter is undefined. + * + * @param context + * The application-defined context parameter to pass to the function. + * + * @param work + * The application-defined function to invoke on the target queue. The first + * parameter passed to this function is the context provided to + * dispatch_async_f(). + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW +void +dispatch_async_f(dispatch_queue_t queue, + void *_Nullable context, dispatch_function_t work); + +/*! + * @function dispatch_sync + * + * @abstract + * Submits a block for synchronous execution on a dispatch queue. + * + * @discussion + * Submits a workitem to a dispatch queue like dispatch_async(), however + * dispatch_sync() will not return until the workitem has finished. + * + * Work items submitted to a queue with dispatch_sync() do not observe certain + * queue attributes of that queue when invoked (such as autorelease frequency + * and QOS class). + * + * Calls to dispatch_sync() targeting the current queue will result + * in dead-lock. Use of dispatch_sync() is also subject to the same + * multi-party dead-lock problems that may result from the use of a mutex. + * Use of dispatch_async() is preferred. + * + * Unlike dispatch_async(), no retain is performed on the target queue. Because + * calls to this function are synchronous, the dispatch_sync() "borrows" the + * reference of the caller. + * + * As an optimization, dispatch_sync() invokes the workitem on the thread which + * submitted the workitem, except when the passed queue is the main queue or + * a queue targetting it (See dispatch_queue_main_t, + * dispatch_set_target_queue()). + * + * @param queue + * The target dispatch queue to which the block is submitted. + * The result of passing NULL in this parameter is undefined. + * + * @param block + * The block to be invoked on the target dispatch queue. + * The result of passing NULL in this parameter is undefined. + */ +#ifdef __BLOCKS__ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_sync(dispatch_queue_t queue, DISPATCH_NOESCAPE dispatch_block_t block); +#endif + +/*! + * @function dispatch_sync_f + * + * @abstract + * Submits a function for synchronous execution on a dispatch queue. + * + * @discussion + * See dispatch_sync() for details. + * + * @param queue + * The target dispatch queue to which the function is submitted. + * The result of passing NULL in this parameter is undefined. + * + * @param context + * The application-defined context parameter to pass to the function. + * + * @param work + * The application-defined function to invoke on the target queue. The first + * parameter passed to this function is the context provided to + * dispatch_sync_f(). + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW +void +dispatch_sync_f(dispatch_queue_t queue, + void *_Nullable context, dispatch_function_t work); + +/*! + * @function dispatch_async_and_wait + * + * @abstract + * Submits a block for synchronous execution on a dispatch queue. + * + * @discussion + * Submits a workitem to a dispatch queue like dispatch_async(), however + * dispatch_async_and_wait() will not return until the workitem has finished. + * + * Like functions of the dispatch_sync family, dispatch_async_and_wait() is + * subject to dead-lock (See dispatch_sync() for details). + * + * However, dispatch_async_and_wait() differs from functions of the + * dispatch_sync family in two fundamental ways: how it respects queue + * attributes and how it chooses the execution context invoking the workitem. + * + * <b>Differences with dispatch_sync()</b> + * + * Work items submitted to a queue with dispatch_async_and_wait() observe all + * queue attributes of that queue when invoked (inluding autorelease frequency + * or QOS class). + * + * When the runtime has brought up a thread to invoke the asynchronous workitems + * already submitted to the specified queue, that servicing thread will also be + * used to execute synchronous work submitted to the queue with + * dispatch_async_and_wait(). + * + * However, if the runtime has not brought up a thread to service the specified + * queue (because it has no workitems enqueued, or only synchronous workitems), + * then dispatch_async_and_wait() will invoke the workitem on the calling thread, + * similar to the behaviour of functions in the dispatch_sync family. + * + * As an exception, if the queue the work is submitted to doesn't target + * a global concurrent queue (for example because it targets the main queue), + * then the workitem will never be invoked by the thread calling + * dispatch_async_and_wait(). + * + * In other words, dispatch_async_and_wait() is similar to submitting + * a dispatch_block_create()d workitem to a queue and then waiting on it, as + * shown in the code example below. However, dispatch_async_and_wait() is + * significantly more efficient when a new thread is not required to execute + * the workitem (as it will use the stack of the submitting thread instead of + * requiring heap allocations). + * + * <code> + * dispatch_block_t b = dispatch_block_create(0, block); + * dispatch_async(queue, b); + * dispatch_block_wait(b, DISPATCH_TIME_FOREVER); + * Block_release(b); + * </code> + * + * @param queue + * The target dispatch queue to which the block is submitted. + * The result of passing NULL in this parameter is undefined. + * + * @param block + * The block to be invoked on the target dispatch queue. + * The result of passing NULL in this parameter is undefined. + */ +#ifdef __BLOCKS__ +API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_async_and_wait(dispatch_queue_t queue, + DISPATCH_NOESCAPE dispatch_block_t block); +#endif + +/*! + * @function dispatch_async_and_wait_f + * + * @abstract + * Submits a function for synchronous execution on a dispatch queue. + * + * @discussion + * See dispatch_async_and_wait() for details. + * + * @param queue + * The target dispatch queue to which the function is submitted. + * The result of passing NULL in this parameter is undefined. + * + * @param context + * The application-defined context parameter to pass to the function. + * + * @param work + * The application-defined function to invoke on the target queue. The first + * parameter passed to this function is the context provided to + * dispatch_async_and_wait_f(). + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW +void +dispatch_async_and_wait_f(dispatch_queue_t queue, + void *_Nullable context, dispatch_function_t work); + + +#if defined(__APPLE__) && \ + (defined(__IPHONE_OS_VERSION_MIN_REQUIRED) && \ + __IPHONE_OS_VERSION_MIN_REQUIRED < __IPHONE_7_0) || \ + (defined(__MAC_OS_X_VERSION_MIN_REQUIRED) && \ + __MAC_OS_X_VERSION_MIN_REQUIRED < __MAC_10_9) +#define DISPATCH_APPLY_AUTO_AVAILABLE 0 +#define DISPATCH_APPLY_QUEUE_ARG_NULLABILITY _Nonnull +#else +#define DISPATCH_APPLY_AUTO_AVAILABLE 1 +#define DISPATCH_APPLY_QUEUE_ARG_NULLABILITY _Nullable +#endif + +/*! + * @constant DISPATCH_APPLY_AUTO + * + * @abstract + * Constant to pass to dispatch_apply() or dispatch_apply_f() to request that + * the system automatically use worker threads that match the configuration of + * the current thread as closely as possible. + * + * @discussion + * When submitting a block for parallel invocation, passing this constant as the + * queue argument will automatically use the global concurrent queue that + * matches the Quality of Service of the caller most closely. + * + * No assumptions should be made about which global concurrent queue will + * actually be used. + * + * Using this constant deploys backward to macOS 10.9, iOS 7.0 and any tvOS or + * watchOS version. + */ +#if DISPATCH_APPLY_AUTO_AVAILABLE +#define DISPATCH_APPLY_AUTO ((dispatch_queue_t _Nonnull)0) +#endif + +/*! + * @function dispatch_apply + * + * @abstract + * Submits a block to a dispatch queue for parallel invocation. + * + * @discussion + * Submits a block to a dispatch queue for parallel invocation. This function + * waits for the task block to complete before returning. If the specified queue + * is concurrent, the block may be invoked concurrently, and it must therefore + * be reentrant safe. + * + * Each invocation of the block will be passed the current index of iteration. + * + * @param iterations + * The number of iterations to perform. + * + * @param queue + * The dispatch queue to which the block is submitted. + * The preferred value to pass is DISPATCH_APPLY_AUTO to automatically use + * a queue appropriate for the calling thread. + * + * @param block + * The block to be invoked the specified number of iterations. + * The result of passing NULL in this parameter is undefined. + */ +#ifdef __BLOCKS__ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL3 DISPATCH_NOTHROW +void +dispatch_apply(size_t iterations, + dispatch_queue_t DISPATCH_APPLY_QUEUE_ARG_NULLABILITY queue, + DISPATCH_NOESCAPE void (^block)(size_t)); +#endif + +/*! + * @function dispatch_apply_f + * + * @abstract + * Submits a function to a dispatch queue for parallel invocation. + * + * @discussion + * See dispatch_apply() for details. + * + * @param iterations + * The number of iterations to perform. + * + * @param queue + * The dispatch queue to which the function is submitted. + * The preferred value to pass is DISPATCH_APPLY_AUTO to automatically use + * a queue appropriate for the calling thread. + * + * @param context + * The application-defined context parameter to pass to the function. + * + * @param work + * The application-defined function to invoke on the specified queue. The first + * parameter passed to this function is the context provided to + * dispatch_apply_f(). The second parameter passed to this function is the + * current index of iteration. + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL4 DISPATCH_NOTHROW +void +dispatch_apply_f(size_t iterations, + dispatch_queue_t DISPATCH_APPLY_QUEUE_ARG_NULLABILITY queue, + void *_Nullable context, void (*work)(void *_Nullable, size_t)); + +/*! + * @function dispatch_get_current_queue + * + * @abstract + * Returns the queue on which the currently executing block is running. + * + * @discussion + * Returns the queue on which the currently executing block is running. + * + * When dispatch_get_current_queue() is called outside of the context of a + * submitted block, it will return the default concurrent queue. + * + * Recommended for debugging and logging purposes only: + * The code must not make any assumptions about the queue returned, unless it + * is one of the global queues or a queue the code has itself created. + * The code must not assume that synchronous execution onto a queue is safe + * from deadlock if that queue is not the one returned by + * dispatch_get_current_queue(). + * + * When dispatch_get_current_queue() is called on the main thread, it may + * or may not return the same value as dispatch_get_main_queue(). Comparing + * the two is not a valid way to test whether code is executing on the + * main thread (see dispatch_assert_queue() and dispatch_assert_queue_not()). + * + * This function is deprecated and will be removed in a future release. + * + * @result + * Returns the current queue. + */ +API_DEPRECATED("unsupported interface", macos(10.6,10.9), ios(4.0,6.0)) +DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW +dispatch_queue_t +dispatch_get_current_queue(void); + +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT +struct dispatch_queue_s _dispatch_main_q; + +/*! + * @function dispatch_get_main_queue + * + * @abstract + * Returns the default queue that is bound to the main thread. + * + * @discussion + * In order to invoke blocks submitted to the main queue, the application must + * call dispatch_main(), NSApplicationMain(), or use a CFRunLoop on the main + * thread. + * + * The main queue is meant to be used in application context to interact with + * the main thread and the main runloop. + * + * Because the main queue doesn't behave entirely like a regular serial queue, + * it may have unwanted side-effects when used in processes that are not UI apps + * (daemons). For such processes, the main queue should be avoided. + * + * @see dispatch_queue_main_t + * + * @result + * Returns the main queue. This queue is created automatically on behalf of + * the main thread before main() is called. + */ +DISPATCH_INLINE DISPATCH_ALWAYS_INLINE DISPATCH_CONST DISPATCH_NOTHROW +dispatch_queue_main_t +dispatch_get_main_queue(void) +{ + return DISPATCH_GLOBAL_OBJECT(dispatch_queue_main_t, _dispatch_main_q); +} + +/*! + * @typedef dispatch_queue_priority_t + * Type of dispatch_queue_priority + * + * @constant DISPATCH_QUEUE_PRIORITY_HIGH + * Items dispatched to the queue will run at high priority, + * i.e. the queue will be scheduled for execution before + * any default priority or low priority queue. + * + * @constant DISPATCH_QUEUE_PRIORITY_DEFAULT + * Items dispatched to the queue will run at the default + * priority, i.e. the queue will be scheduled for execution + * after all high priority queues have been scheduled, but + * before any low priority queues have been scheduled. + * + * @constant DISPATCH_QUEUE_PRIORITY_LOW + * Items dispatched to the queue will run at low priority, + * i.e. the queue will be scheduled for execution after all + * default priority and high priority queues have been + * scheduled. + * + * @constant DISPATCH_QUEUE_PRIORITY_BACKGROUND + * Items dispatched to the queue will run at background priority, i.e. the queue + * will be scheduled for execution after all higher priority queues have been + * scheduled and the system will run items on this queue on a thread with + * background status as per setpriority(2) (i.e. disk I/O is throttled and the + * thread's scheduling priority is set to lowest value). + */ +#define DISPATCH_QUEUE_PRIORITY_HIGH 2 +#define DISPATCH_QUEUE_PRIORITY_DEFAULT 0 +#define DISPATCH_QUEUE_PRIORITY_LOW (-2) +#define DISPATCH_QUEUE_PRIORITY_BACKGROUND INT16_MIN + +typedef long dispatch_queue_priority_t; + +/*! + * @function dispatch_get_global_queue + * + * @abstract + * Returns a well-known global concurrent queue of a given quality of service + * class. + * + * @discussion + * See dispatch_queue_global_t. + * + * @param identifier + * A quality of service class defined in qos_class_t or a priority defined in + * dispatch_queue_priority_t. + * + * It is recommended to use quality of service class values to identify the + * well-known global concurrent queues: + * - QOS_CLASS_USER_INTERACTIVE + * - QOS_CLASS_USER_INITIATED + * - QOS_CLASS_DEFAULT + * - QOS_CLASS_UTILITY + * - QOS_CLASS_BACKGROUND + * + * The global concurrent queues may still be identified by their priority, + * which map to the following QOS classes: + * - DISPATCH_QUEUE_PRIORITY_HIGH: QOS_CLASS_USER_INITIATED + * - DISPATCH_QUEUE_PRIORITY_DEFAULT: QOS_CLASS_DEFAULT + * - DISPATCH_QUEUE_PRIORITY_LOW: QOS_CLASS_UTILITY + * - DISPATCH_QUEUE_PRIORITY_BACKGROUND: QOS_CLASS_BACKGROUND + * + * @param flags + * Reserved for future use. Passing any value other than zero may result in + * a NULL return value. + * + * @result + * Returns the requested global queue or NULL if the requested global queue + * does not exist. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_CONST DISPATCH_WARN_RESULT DISPATCH_NOTHROW +dispatch_queue_global_t +dispatch_get_global_queue(intptr_t identifier, uintptr_t flags); + +/*! + * @typedef dispatch_queue_attr_t + * + * @abstract + * Attribute for dispatch queues. + */ +DISPATCH_DECL(dispatch_queue_attr); + +/*! + * @const DISPATCH_QUEUE_SERIAL + * + * @discussion + * An attribute that can be used to create a dispatch queue that invokes blocks + * serially in FIFO order. + * + * See dispatch_queue_serial_t. + */ +#define DISPATCH_QUEUE_SERIAL NULL + +/*! + * @const DISPATCH_QUEUE_SERIAL_INACTIVE + * + * @discussion + * An attribute that can be used to create a dispatch queue that invokes blocks + * serially in FIFO order, and that is initially inactive. + * + * See dispatch_queue_attr_make_initially_inactive(). + */ +#define DISPATCH_QUEUE_SERIAL_INACTIVE \ + dispatch_queue_attr_make_initially_inactive(DISPATCH_QUEUE_SERIAL) + +/*! + * @const DISPATCH_QUEUE_CONCURRENT + * + * @discussion + * An attribute that can be used to create a dispatch queue that may invoke + * blocks concurrently and supports barrier blocks submitted with the dispatch + * barrier API. + * + * See dispatch_queue_concurrent_t. + */ +#define DISPATCH_QUEUE_CONCURRENT \ + DISPATCH_GLOBAL_OBJECT(dispatch_queue_attr_t, \ + _dispatch_queue_attr_concurrent) +API_AVAILABLE(macos(10.7), ios(4.3)) +DISPATCH_EXPORT +struct dispatch_queue_attr_s _dispatch_queue_attr_concurrent; + +/*! + * @const DISPATCH_QUEUE_CONCURRENT_INACTIVE + * + * @discussion + * An attribute that can be used to create a dispatch queue that may invoke + * blocks concurrently and supports barrier blocks submitted with the dispatch + * barrier API, and that is initially inactive. + * + * See dispatch_queue_attr_make_initially_inactive(). + */ +#define DISPATCH_QUEUE_CONCURRENT_INACTIVE \ + dispatch_queue_attr_make_initially_inactive(DISPATCH_QUEUE_CONCURRENT) + +/*! + * @function dispatch_queue_attr_make_initially_inactive + * + * @abstract + * Returns an attribute value which may be provided to dispatch_queue_create() + * or dispatch_queue_create_with_target(), in order to make the created queue + * initially inactive. + * + * @discussion + * Dispatch queues may be created in an inactive state. Queues in this state + * have to be activated before any blocks associated with them will be invoked. + * + * A queue in inactive state cannot be deallocated, dispatch_activate() must be + * called before the last reference to a queue created with this attribute is + * released. + * + * The target queue of a queue in inactive state can be changed using + * dispatch_set_target_queue(). Change of target queue is no longer permitted + * once an initially inactive queue has been activated. + * + * @param attr + * A queue attribute value to be combined with the initially inactive attribute. + * + * @return + * Returns an attribute value which may be provided to dispatch_queue_create() + * and dispatch_queue_create_with_target(). + * The new value combines the attributes specified by the 'attr' parameter with + * the initially inactive attribute. + */ +API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0)) +DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW +dispatch_queue_attr_t +dispatch_queue_attr_make_initially_inactive( + dispatch_queue_attr_t _Nullable attr); + +/*! + * @const DISPATCH_QUEUE_SERIAL_WITH_AUTORELEASE_POOL + * + * @discussion + * A dispatch queue created with this attribute invokes blocks serially in FIFO + * order, and surrounds execution of any block submitted asynchronously to it + * with the equivalent of a individual Objective-C <code>@autoreleasepool</code> + * scope. + * + * See dispatch_queue_attr_make_with_autorelease_frequency(). + */ +#define DISPATCH_QUEUE_SERIAL_WITH_AUTORELEASE_POOL \ + dispatch_queue_attr_make_with_autorelease_frequency(\ + DISPATCH_QUEUE_SERIAL, DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM) + +/*! + * @const DISPATCH_QUEUE_CONCURRENT_WITH_AUTORELEASE_POOL + * + * @discussion + * A dispatch queue created with this attribute may invokes blocks concurrently + * and supports barrier blocks submitted with the dispatch barrier API. It also + * surrounds execution of any block submitted asynchronously to it with the + * equivalent of a individual Objective-C <code>@autoreleasepool</code> + * + * See dispatch_queue_attr_make_with_autorelease_frequency(). + */ +#define DISPATCH_QUEUE_CONCURRENT_WITH_AUTORELEASE_POOL \ + dispatch_queue_attr_make_with_autorelease_frequency(\ + DISPATCH_QUEUE_CONCURRENT, DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM) + +/*! + * @typedef dispatch_autorelease_frequency_t + * Values to pass to the dispatch_queue_attr_make_with_autorelease_frequency() + * function. + * + * @const DISPATCH_AUTORELEASE_FREQUENCY_INHERIT + * Dispatch queues with this autorelease frequency inherit the behavior from + * their target queue. This is the default behavior for manually created queues. + * + * @const DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM + * Dispatch queues with this autorelease frequency push and pop an autorelease + * pool around the execution of every block that was submitted to it + * asynchronously. + * @see dispatch_queue_attr_make_with_autorelease_frequency(). + * + * @const DISPATCH_AUTORELEASE_FREQUENCY_NEVER + * Dispatch queues with this autorelease frequency never set up an individual + * autorelease pool around the execution of a block that is submitted to it + * asynchronously. This is the behavior of the global concurrent queues. + */ +DISPATCH_ENUM(dispatch_autorelease_frequency, unsigned long, + DISPATCH_AUTORELEASE_FREQUENCY_INHERIT DISPATCH_ENUM_API_AVAILABLE( + macos(10.12), ios(10.0), tvos(10.0), watchos(3.0)) = 0, + DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM DISPATCH_ENUM_API_AVAILABLE( + macos(10.12), ios(10.0), tvos(10.0), watchos(3.0)) = 1, + DISPATCH_AUTORELEASE_FREQUENCY_NEVER DISPATCH_ENUM_API_AVAILABLE( + macos(10.12), ios(10.0), tvos(10.0), watchos(3.0)) = 2, +); + +/*! + * @function dispatch_queue_attr_make_with_autorelease_frequency + * + * @abstract + * Returns a dispatch queue attribute value with the autorelease frequency + * set to the specified value. + * + * @discussion + * When a queue uses the per-workitem autorelease frequency (either directly + * or inherithed from its target queue), any block submitted asynchronously to + * this queue (via dispatch_async(), dispatch_barrier_async(), + * dispatch_group_notify(), etc...) is executed as if surrounded by a individual + * Objective-C <code>@autoreleasepool</code> scope. + * + * Autorelease frequency has no effect on blocks that are submitted + * synchronously to a queue (via dispatch_sync(), dispatch_barrier_sync()). + * + * The global concurrent queues have the DISPATCH_AUTORELEASE_FREQUENCY_NEVER + * behavior. Manually created dispatch queues use + * DISPATCH_AUTORELEASE_FREQUENCY_INHERIT by default. + * + * Queues created with this attribute cannot change target queues after having + * been activated. See dispatch_set_target_queue() and dispatch_activate(). + * + * @param attr + * A queue attribute value to be combined with the specified autorelease + * frequency or NULL. + * + * @param frequency + * The requested autorelease frequency. + * + * @return + * Returns an attribute value which may be provided to dispatch_queue_create() + * or NULL if an invalid autorelease frequency was requested. + * This new value combines the attributes specified by the 'attr' parameter and + * the chosen autorelease frequency. + */ +API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0)) +DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW +dispatch_queue_attr_t +dispatch_queue_attr_make_with_autorelease_frequency( + dispatch_queue_attr_t _Nullable attr, + dispatch_autorelease_frequency_t frequency); + +/*! + * @function dispatch_queue_attr_make_with_qos_class + * + * @abstract + * Returns an attribute value which may be provided to dispatch_queue_create() + * or dispatch_queue_create_with_target(), in order to assign a QOS class and + * relative priority to the queue. + * + * @discussion + * When specified in this manner, the QOS class and relative priority take + * precedence over those inherited from the dispatch queue's target queue (if + * any) as long that does not result in a lower QOS class and relative priority. + * + * The global queue priorities map to the following QOS classes: + * - DISPATCH_QUEUE_PRIORITY_HIGH: QOS_CLASS_USER_INITIATED + * - DISPATCH_QUEUE_PRIORITY_DEFAULT: QOS_CLASS_DEFAULT + * - DISPATCH_QUEUE_PRIORITY_LOW: QOS_CLASS_UTILITY + * - DISPATCH_QUEUE_PRIORITY_BACKGROUND: QOS_CLASS_BACKGROUND + * + * Example: + * <code> + * dispatch_queue_t queue; + * dispatch_queue_attr_t attr; + * attr = dispatch_queue_attr_make_with_qos_class(DISPATCH_QUEUE_SERIAL, + * QOS_CLASS_UTILITY, 0); + * queue = dispatch_queue_create("com.example.myqueue", attr); + * </code> + * + * The QOS class and relative priority set this way on a queue have no effect on + * blocks that are submitted synchronously to a queue (via dispatch_sync(), + * dispatch_barrier_sync()). + * + * @param attr + * A queue attribute value to be combined with the QOS class, or NULL. + * + * @param qos_class + * A QOS class value: + * - QOS_CLASS_USER_INTERACTIVE + * - QOS_CLASS_USER_INITIATED + * - QOS_CLASS_DEFAULT + * - QOS_CLASS_UTILITY + * - QOS_CLASS_BACKGROUND + * Passing any other value results in NULL being returned. + * + * @param relative_priority + * A relative priority within the QOS class. This value is a negative + * offset from the maximum supported scheduler priority for the given class. + * Passing a value greater than zero or less than QOS_MIN_RELATIVE_PRIORITY + * results in NULL being returned. + * + * @return + * Returns an attribute value which may be provided to dispatch_queue_create() + * and dispatch_queue_create_with_target(), or NULL if an invalid QOS class was + * requested. + * The new value combines the attributes specified by the 'attr' parameter and + * the new QOS class and relative priority. + */ +API_AVAILABLE(macos(10.10), ios(8.0)) +DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW +dispatch_queue_attr_t +dispatch_queue_attr_make_with_qos_class(dispatch_queue_attr_t _Nullable attr, + dispatch_qos_class_t qos_class, int relative_priority); + +/*! + * @const DISPATCH_TARGET_QUEUE_DEFAULT + * @discussion Constant to pass to the dispatch_queue_create_with_target(), + * dispatch_set_target_queue() and dispatch_source_create() functions to + * indicate that the default target queue for the object type in question + * should be used. + */ +#define DISPATCH_TARGET_QUEUE_DEFAULT NULL + +/*! + * @function dispatch_queue_create_with_target + * + * @abstract + * Creates a new dispatch queue with a specified target queue. + * + * @discussion + * Dispatch queues created with the DISPATCH_QUEUE_SERIAL or a NULL attribute + * invoke blocks serially in FIFO order. + * + * Dispatch queues created with the DISPATCH_QUEUE_CONCURRENT attribute may + * invoke blocks concurrently (similarly to the global concurrent queues, but + * potentially with more overhead), and support barrier blocks submitted with + * the dispatch barrier API, which e.g. enables the implementation of efficient + * reader-writer schemes. + * + * When a dispatch queue is no longer needed, it should be released with + * dispatch_release(). Note that any pending blocks submitted asynchronously to + * a queue will hold a reference to that queue. Therefore a queue will not be + * deallocated until all pending blocks have finished. + * + * When using a dispatch queue attribute @a attr specifying a QoS class (derived + * from the result of dispatch_queue_attr_make_with_qos_class()), passing the + * result of dispatch_get_global_queue() in @a target will ignore the QoS class + * of that global queue and will use the global queue with the QoS class + * specified by attr instead. + * + * Queues created with dispatch_queue_create_with_target() cannot have their + * target queue changed, unless created inactive (See + * dispatch_queue_attr_make_initially_inactive()), in which case the target + * queue can be changed until the newly created queue is activated with + * dispatch_activate(). + * + * @param label + * A string label to attach to the queue. + * This parameter is optional and may be NULL. + * + * @param attr + * A predefined attribute such as DISPATCH_QUEUE_SERIAL, + * DISPATCH_QUEUE_CONCURRENT, or the result of a call to + * a dispatch_queue_attr_make_with_* function. + * + * @param target + * The target queue for the newly created queue. The target queue is retained. + * If this parameter is DISPATCH_TARGET_QUEUE_DEFAULT, sets the queue's target + * queue to the default target queue for the given queue type. + * + * @result + * The newly created dispatch queue. + */ +API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0)) +DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT +DISPATCH_NOTHROW +dispatch_queue_t +dispatch_queue_create_with_target(const char *_Nullable label, + dispatch_queue_attr_t _Nullable attr, dispatch_queue_t _Nullable target) + DISPATCH_ALIAS_V2(dispatch_queue_create_with_target); + +/*! + * @function dispatch_queue_create + * + * @abstract + * Creates a new dispatch queue to which blocks may be submitted. + * + * @discussion + * Dispatch queues created with the DISPATCH_QUEUE_SERIAL or a NULL attribute + * invoke blocks serially in FIFO order. + * + * Dispatch queues created with the DISPATCH_QUEUE_CONCURRENT attribute may + * invoke blocks concurrently (similarly to the global concurrent queues, but + * potentially with more overhead), and support barrier blocks submitted with + * the dispatch barrier API, which e.g. enables the implementation of efficient + * reader-writer schemes. + * + * When a dispatch queue is no longer needed, it should be released with + * dispatch_release(). Note that any pending blocks submitted asynchronously to + * a queue will hold a reference to that queue. Therefore a queue will not be + * deallocated until all pending blocks have finished. + * + * Passing the result of the dispatch_queue_attr_make_with_qos_class() function + * to the attr parameter of this function allows a quality of service class and + * relative priority to be specified for the newly created queue. + * The quality of service class so specified takes precedence over the quality + * of service class of the newly created dispatch queue's target queue (if any) + * as long that does not result in a lower QOS class and relative priority. + * + * When no quality of service class is specified, the target queue of a newly + * created dispatch queue is the default priority global concurrent queue. + * + * @param label + * A string label to attach to the queue. + * This parameter is optional and may be NULL. + * + * @param attr + * A predefined attribute such as DISPATCH_QUEUE_SERIAL, + * DISPATCH_QUEUE_CONCURRENT, or the result of a call to + * a dispatch_queue_attr_make_with_* function. + * + * @result + * The newly created dispatch queue. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT +DISPATCH_NOTHROW +dispatch_queue_t +dispatch_queue_create(const char *_Nullable label, + dispatch_queue_attr_t _Nullable attr); + +/*! + * @const DISPATCH_CURRENT_QUEUE_LABEL + * @discussion Constant to pass to the dispatch_queue_get_label() function to + * retrieve the label of the current queue. + */ +#define DISPATCH_CURRENT_QUEUE_LABEL NULL + +/*! + * @function dispatch_queue_get_label + * + * @abstract + * Returns the label of the given queue, as specified when the queue was + * created, or the empty string if a NULL label was specified. + * + * Passing DISPATCH_CURRENT_QUEUE_LABEL will return the label of the current + * queue. + * + * @param queue + * The queue to query, or DISPATCH_CURRENT_QUEUE_LABEL. + * + * @result + * The label of the queue. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW +const char * +dispatch_queue_get_label(dispatch_queue_t _Nullable queue); + +/*! + * @function dispatch_queue_get_qos_class + * + * @abstract + * Returns the QOS class and relative priority of the given queue. + * + * @discussion + * If the given queue was created with an attribute value returned from + * dispatch_queue_attr_make_with_qos_class(), this function returns the QOS + * class and relative priority specified at that time; for any other attribute + * value it returns a QOS class of QOS_CLASS_UNSPECIFIED and a relative + * priority of 0. + * + * If the given queue is one of the global queues, this function returns its + * assigned QOS class value as documented under dispatch_get_global_queue() and + * a relative priority of 0; in the case of the main queue it returns the QOS + * value provided by qos_class_main() and a relative priority of 0. + * + * @param queue + * The queue to query. + * + * @param relative_priority_ptr + * A pointer to an int variable to be filled with the relative priority offset + * within the QOS class, or NULL. + * + * @return + * A QOS class value: + * - QOS_CLASS_USER_INTERACTIVE + * - QOS_CLASS_USER_INITIATED + * - QOS_CLASS_DEFAULT + * - QOS_CLASS_UTILITY + * - QOS_CLASS_BACKGROUND + * - QOS_CLASS_UNSPECIFIED + */ +API_AVAILABLE(macos(10.10), ios(8.0)) +DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_NONNULL1 DISPATCH_NOTHROW +dispatch_qos_class_t +dispatch_queue_get_qos_class(dispatch_queue_t queue, + int *_Nullable relative_priority_ptr); + +/*! + * @function dispatch_set_target_queue + * + * @abstract + * Sets the target queue for the given object. + * + * @discussion + * An object's target queue is responsible for processing the object. + * + * When no quality of service class and relative priority is specified for a + * dispatch queue at the time of creation, a dispatch queue's quality of service + * class is inherited from its target queue. The dispatch_get_global_queue() + * function may be used to obtain a target queue of a specific quality of + * service class, however the use of dispatch_queue_attr_make_with_qos_class() + * is recommended instead. + * + * Blocks submitted to a serial queue whose target queue is another serial + * queue will not be invoked concurrently with blocks submitted to the target + * queue or to any other queue with that same target queue. + * + * The result of introducing a cycle into the hierarchy of target queues is + * undefined. + * + * A dispatch source's target queue specifies where its event handler and + * cancellation handler blocks will be submitted. + * + * A dispatch I/O channel's target queue specifies where where its I/O + * operations are executed. If the channel's target queue's priority is set to + * DISPATCH_QUEUE_PRIORITY_BACKGROUND, then the I/O operations performed by + * dispatch_io_read() or dispatch_io_write() on that queue will be + * throttled when there is I/O contention. + * + * For all other dispatch object types, the only function of the target queue + * is to determine where an object's finalizer function is invoked. + * + * In general, changing the target queue of an object is an asynchronous + * operation that doesn't take effect immediately, and doesn't affect blocks + * already associated with the specified object. + * + * However, if an object is inactive at the time dispatch_set_target_queue() is + * called, then the target queue change takes effect immediately, and will + * affect blocks already associated with the specified object. After an + * initially inactive object has been activated, calling + * dispatch_set_target_queue() results in an assertion and the process being + * terminated. + * + * If a dispatch queue is active and targeted by other dispatch objects, + * changing its target queue results in undefined behavior. + * + * @param object + * The object to modify. + * The result of passing NULL in this parameter is undefined. + * + * @param queue + * The new target queue for the object. The queue is retained, and the + * previous target queue, if any, is released. + * If queue is DISPATCH_TARGET_QUEUE_DEFAULT, set the object's target queue + * to the default target queue for the given object type. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NOTHROW +void +dispatch_set_target_queue(dispatch_object_t object, + dispatch_queue_t _Nullable queue); + +/*! + * @function dispatch_main + * + * @abstract + * Execute blocks submitted to the main queue. + * + * @discussion + * This function "parks" the main thread and waits for blocks to be submitted + * to the main queue. This function never returns. + * + * Applications that call NSApplicationMain() or CFRunLoopRun() on the + * main thread do not need to call dispatch_main(). + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NOTHROW DISPATCH_NORETURN +void +dispatch_main(void); + +/*! + * @function dispatch_after + * + * @abstract + * Schedule a block for execution on a given queue at a specified time. + * + * @discussion + * Passing DISPATCH_TIME_NOW as the "when" parameter is supported, but not as + * optimal as calling dispatch_async() instead. Passing DISPATCH_TIME_FOREVER + * is undefined. + * + * @param when + * A temporal milestone returned by dispatch_time() or dispatch_walltime(). + * + * @param queue + * A queue to which the given block will be submitted at the specified time. + * The result of passing NULL in this parameter is undefined. + * + * @param block + * The block of code to execute. + * The result of passing NULL in this parameter is undefined. + */ +#ifdef __BLOCKS__ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NONNULL3 DISPATCH_NOTHROW +void +dispatch_after(dispatch_time_t when, dispatch_queue_t queue, + dispatch_block_t block); +#endif + +/*! + * @function dispatch_after_f + * + * @abstract + * Schedule a function for execution on a given queue at a specified time. + * + * @discussion + * See dispatch_after() for details. + * + * @param when + * A temporal milestone returned by dispatch_time() or dispatch_walltime(). + * + * @param queue + * A queue to which the given function will be submitted at the specified time. + * The result of passing NULL in this parameter is undefined. + * + * @param context + * The application-defined context parameter to pass to the function. + * + * @param work + * The application-defined function to invoke on the target queue. The first + * parameter passed to this function is the context provided to + * dispatch_after_f(). + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NONNULL4 DISPATCH_NOTHROW +void +dispatch_after_f(dispatch_time_t when, dispatch_queue_t queue, + void *_Nullable context, dispatch_function_t work); + +/*! + * @functiongroup Dispatch Barrier API + * The dispatch barrier API is a mechanism for submitting barrier blocks to a + * dispatch queue, analogous to the dispatch_async()/dispatch_sync() API. + * It enables the implementation of efficient reader/writer schemes. + * Barrier blocks only behave specially when submitted to queues created with + * the DISPATCH_QUEUE_CONCURRENT attribute; on such a queue, a barrier block + * will not run until all blocks submitted to the queue earlier have completed, + * and any blocks submitted to the queue after a barrier block will not run + * until the barrier block has completed. + * When submitted to a a global queue or to a queue not created with the + * DISPATCH_QUEUE_CONCURRENT attribute, barrier blocks behave identically to + * blocks submitted with the dispatch_async()/dispatch_sync() API. + */ + +/*! + * @function dispatch_barrier_async + * + * @abstract + * Submits a barrier block for asynchronous execution on a dispatch queue. + * + * @discussion + * Submits a block to a dispatch queue like dispatch_async(), but marks that + * block as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT queues). + * + * See dispatch_async() for details and "Dispatch Barrier API" for a description + * of the barrier semantics. + * + * @param queue + * The target dispatch queue to which the block is submitted. + * The system will hold a reference on the target queue until the block + * has finished. + * The result of passing NULL in this parameter is undefined. + * + * @param block + * The block to submit to the target dispatch queue. This function performs + * Block_copy() and Block_release() on behalf of callers. + * The result of passing NULL in this parameter is undefined. + */ +#ifdef __BLOCKS__ +API_AVAILABLE(macos(10.7), ios(4.3)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_barrier_async(dispatch_queue_t queue, dispatch_block_t block); +#endif + +/*! + * @function dispatch_barrier_async_f + * + * @abstract + * Submits a barrier function for asynchronous execution on a dispatch queue. + * + * @discussion + * Submits a function to a dispatch queue like dispatch_async_f(), but marks + * that function as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT + * queues). + * + * See dispatch_async_f() for details and "Dispatch Barrier API" for a + * description of the barrier semantics. + * + * @param queue + * The target dispatch queue to which the function is submitted. + * The system will hold a reference on the target queue until the function + * has returned. + * The result of passing NULL in this parameter is undefined. + * + * @param context + * The application-defined context parameter to pass to the function. + * + * @param work + * The application-defined function to invoke on the target queue. The first + * parameter passed to this function is the context provided to + * dispatch_barrier_async_f(). + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.7), ios(4.3)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW +void +dispatch_barrier_async_f(dispatch_queue_t queue, + void *_Nullable context, dispatch_function_t work); + +/*! + * @function dispatch_barrier_sync + * + * @abstract + * Submits a barrier block for synchronous execution on a dispatch queue. + * + * @discussion + * Submits a block to a dispatch queue like dispatch_sync(), but marks that + * block as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT queues). + * + * See dispatch_sync() for details and "Dispatch Barrier API" for a description + * of the barrier semantics. + * + * @param queue + * The target dispatch queue to which the block is submitted. + * The result of passing NULL in this parameter is undefined. + * + * @param block + * The block to be invoked on the target dispatch queue. + * The result of passing NULL in this parameter is undefined. + */ +#ifdef __BLOCKS__ +API_AVAILABLE(macos(10.7), ios(4.3)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_barrier_sync(dispatch_queue_t queue, + DISPATCH_NOESCAPE dispatch_block_t block); +#endif + +/*! + * @function dispatch_barrier_sync_f + * + * @abstract + * Submits a barrier function for synchronous execution on a dispatch queue. + * + * @discussion + * Submits a function to a dispatch queue like dispatch_sync_f(), but marks that + * fuction as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT queues). + * + * See dispatch_sync_f() for details. + * + * @param queue + * The target dispatch queue to which the function is submitted. + * The result of passing NULL in this parameter is undefined. + * + * @param context + * The application-defined context parameter to pass to the function. + * + * @param work + * The application-defined function to invoke on the target queue. The first + * parameter passed to this function is the context provided to + * dispatch_barrier_sync_f(). + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.7), ios(4.3)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW +void +dispatch_barrier_sync_f(dispatch_queue_t queue, + void *_Nullable context, dispatch_function_t work); + +/*! + * @function dispatch_barrier_async_and_wait + * + * @abstract + * Submits a block for synchronous execution on a dispatch queue. + * + * @discussion + * Submits a block to a dispatch queue like dispatch_async_and_wait(), but marks + * that block as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT + * queues). + * + * See "Dispatch Barrier API" for a description of the barrier semantics. + * + * @param queue + * The target dispatch queue to which the block is submitted. + * The result of passing NULL in this parameter is undefined. + * + * @param work + * The application-defined block to invoke on the target queue. + * The result of passing NULL in this parameter is undefined. + */ +#ifdef __BLOCKS__ +API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_barrier_async_and_wait(dispatch_queue_t queue, + DISPATCH_NOESCAPE dispatch_block_t block); +#endif + +/*! + * @function dispatch_barrier_async_and_wait_f + * + * @abstract + * Submits a function for synchronous execution on a dispatch queue. + * + * @discussion + * Submits a function to a dispatch queue like dispatch_async_and_wait_f(), but + * marks that function as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT + * queues). + * + * See "Dispatch Barrier API" for a description of the barrier semantics. + * + * @param queue + * The target dispatch queue to which the function is submitted. + * The result of passing NULL in this parameter is undefined. + * + * @param context + * The application-defined context parameter to pass to the function. + * + * @param work + * The application-defined function to invoke on the target queue. The first + * parameter passed to this function is the context provided to + * dispatch_barrier_async_and_wait_f(). + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW +void +dispatch_barrier_async_and_wait_f(dispatch_queue_t queue, + void *_Nullable context, dispatch_function_t work); + +/*! + * @functiongroup Dispatch queue-specific contexts + * This API allows different subsystems to associate context to a shared queue + * without risk of collision and to retrieve that context from blocks executing + * on that queue or any of its child queues in the target queue hierarchy. + */ + +/*! + * @function dispatch_queue_set_specific + * + * @abstract + * Associates a subsystem-specific context with a dispatch queue, for a key + * unique to the subsystem. + * + * @discussion + * The specified destructor will be invoked with the context on the default + * priority global concurrent queue when a new context is set for the same key, + * or after all references to the queue have been released. + * + * @param queue + * The dispatch queue to modify. + * The result of passing NULL in this parameter is undefined. + * + * @param key + * The key to set the context for, typically a pointer to a static variable + * specific to the subsystem. Keys are only compared as pointers and never + * dereferenced. Passing a string constant directly is not recommended. + * The NULL key is reserved and attempts to set a context for it are ignored. + * + * @param context + * The new subsystem-specific context for the object. This may be NULL. + * + * @param destructor + * The destructor function pointer. This may be NULL and is ignored if context + * is NULL. + */ +API_AVAILABLE(macos(10.7), ios(5.0)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW +void +dispatch_queue_set_specific(dispatch_queue_t queue, const void *key, + void *_Nullable context, dispatch_function_t _Nullable destructor); + +/*! + * @function dispatch_queue_get_specific + * + * @abstract + * Returns the subsystem-specific context associated with a dispatch queue, for + * a key unique to the subsystem. + * + * @discussion + * Returns the context for the specified key if it has been set on the specified + * queue. + * + * @param queue + * The dispatch queue to query. + * The result of passing NULL in this parameter is undefined. + * + * @param key + * The key to get the context for, typically a pointer to a static variable + * specific to the subsystem. Keys are only compared as pointers and never + * dereferenced. Passing a string constant directly is not recommended. + * + * @result + * The context for the specified key or NULL if no context was found. + */ +API_AVAILABLE(macos(10.7), ios(5.0)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_PURE DISPATCH_WARN_RESULT +DISPATCH_NOTHROW +void *_Nullable +dispatch_queue_get_specific(dispatch_queue_t queue, const void *key); + +/*! + * @function dispatch_get_specific + * + * @abstract + * Returns the current subsystem-specific context for a key unique to the + * subsystem. + * + * @discussion + * When called from a block executing on a queue, returns the context for the + * specified key if it has been set on the queue, otherwise returns the result + * of dispatch_get_specific() executed on the queue's target queue or NULL + * if the current queue is a global concurrent queue. + * + * @param key + * The key to get the context for, typically a pointer to a static variable + * specific to the subsystem. Keys are only compared as pointers and never + * dereferenced. Passing a string constant directly is not recommended. + * + * @result + * The context for the specified key or NULL if no context was found. + */ +API_AVAILABLE(macos(10.7), ios(5.0)) +DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW +void *_Nullable +dispatch_get_specific(const void *key); + +/*! + * @functiongroup Dispatch assertion API + * + * This API asserts at runtime that code is executing in (or out of) the context + * of a given queue. It can be used to check that a block accessing a resource + * does so from the proper queue protecting the resource. It also can be used + * to verify that a block that could cause a deadlock if run on a given queue + * never executes on that queue. + */ + +/*! + * @function dispatch_assert_queue + * + * @abstract + * Verifies that the current block is executing on a given dispatch queue. + * + * @discussion + * Some code expects to be run on a specific dispatch queue. This function + * verifies that that expectation is true. + * + * If the currently executing block was submitted to the specified queue or to + * any queue targeting it (see dispatch_set_target_queue()), this function + * returns. + * + * If the currently executing block was submitted with a synchronous API + * (dispatch_sync(), dispatch_barrier_sync(), ...), the context of the + * submitting block is also evaluated (recursively). + * If a synchronously submitting block is found that was itself submitted to + * the specified queue or to any queue targeting it, this function returns. + * + * Otherwise this function asserts: it logs an explanation to the system log and + * terminates the application. + * + * Passing the result of dispatch_get_main_queue() to this function verifies + * that the current block was submitted to the main queue, or to a queue + * targeting it, or is running on the main thread (in any context). + * + * When dispatch_assert_queue() is called outside of the context of a + * submitted block (for example from the context of a thread created manually + * with pthread_create()) then this function will also assert and terminate + * the application. + * + * The variant dispatch_assert_queue_debug() is compiled out when the + * preprocessor macro NDEBUG is defined. (See also assert(3)). + * + * @param queue + * The dispatch queue that the current block is expected to run on. + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0)) +DISPATCH_EXPORT DISPATCH_NONNULL1 +void +dispatch_assert_queue(dispatch_queue_t queue) + DISPATCH_ALIAS_V2(dispatch_assert_queue); + +/*! + * @function dispatch_assert_queue_barrier + * + * @abstract + * Verifies that the current block is executing on a given dispatch queue, + * and that the block acts as a barrier on that queue. + * + * @discussion + * This behaves exactly like dispatch_assert_queue(), with the additional check + * that the current block acts as a barrier on the specified queue, which is + * always true if the specified queue is serial (see DISPATCH_BLOCK_BARRIER or + * dispatch_barrier_async() for details). + * + * The variant dispatch_assert_queue_barrier_debug() is compiled out when the + * preprocessor macro NDEBUG is defined. (See also assert()). + * + * @param queue + * The dispatch queue that the current block is expected to run as a barrier on. + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0)) +DISPATCH_EXPORT DISPATCH_NONNULL1 +void +dispatch_assert_queue_barrier(dispatch_queue_t queue); + +/*! + * @function dispatch_assert_queue_not + * + * @abstract + * Verifies that the current block is not executing on a given dispatch queue. + * + * @discussion + * This function is the equivalent of dispatch_assert_queue() with the test for + * equality inverted. That means that it will terminate the application when + * dispatch_assert_queue() would return, and vice-versa. See discussion there. + * + * The variant dispatch_assert_queue_not_debug() is compiled out when the + * preprocessor macro NDEBUG is defined. (See also assert(3)). + * + * @param queue + * The dispatch queue that the current block is expected not to run on. + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0)) +DISPATCH_EXPORT DISPATCH_NONNULL1 +void +dispatch_assert_queue_not(dispatch_queue_t queue) + DISPATCH_ALIAS_V2(dispatch_assert_queue_not); + +#ifdef NDEBUG +#define dispatch_assert_queue_debug(q) ((void)(0 && (q))) +#define dispatch_assert_queue_barrier_debug(q) ((void)(0 && (q))) +#define dispatch_assert_queue_not_debug(q) ((void)(0 && (q))) +#else +#define dispatch_assert_queue_debug(q) dispatch_assert_queue(q) +#define dispatch_assert_queue_barrier_debug(q) dispatch_assert_queue_barrier(q) +#define dispatch_assert_queue_not_debug(q) dispatch_assert_queue_not(q) +#endif + +__END_DECLS + +DISPATCH_ASSUME_NONNULL_END + +#endif
\ No newline at end of file diff --git a/lib/libc/include/aarch64-macos-gnu/dispatch/semaphore.h b/lib/libc/include/aarch64-macos-gnu/dispatch/semaphore.h new file mode 100644 index 0000000000..225fe41563 --- /dev/null +++ b/lib/libc/include/aarch64-macos-gnu/dispatch/semaphore.h @@ -0,0 +1,117 @@ +/* + * Copyright (c) 2008-2013 Apple Inc. All rights reserved. + * + * @APPLE_APACHE_LICENSE_HEADER_START@ + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * @APPLE_APACHE_LICENSE_HEADER_END@ + */ + +#ifndef __DISPATCH_SEMAPHORE__ +#define __DISPATCH_SEMAPHORE__ + +#ifndef __DISPATCH_INDIRECT__ +#error "Please #include <dispatch/dispatch.h> instead of this file directly." +#include <dispatch/base.h> // for HeaderDoc +#endif + +DISPATCH_ASSUME_NONNULL_BEGIN + +/*! + * @typedef dispatch_semaphore_t + * + * @abstract + * A counting semaphore. + */ +DISPATCH_DECL(dispatch_semaphore); + +__BEGIN_DECLS + +/*! + * @function dispatch_semaphore_create + * + * @abstract + * Creates new counting semaphore with an initial value. + * + * @discussion + * Passing zero for the value is useful for when two threads need to reconcile + * the completion of a particular event. Passing a value greater than zero is + * useful for managing a finite pool of resources, where the pool size is equal + * to the value. + * + * @param value + * The starting value for the semaphore. Passing a value less than zero will + * cause NULL to be returned. + * + * @result + * The newly created semaphore, or NULL on failure. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT +DISPATCH_NOTHROW +dispatch_semaphore_t +dispatch_semaphore_create(intptr_t value); + +/*! + * @function dispatch_semaphore_wait + * + * @abstract + * Wait (decrement) for a semaphore. + * + * @discussion + * Decrement the counting semaphore. If the resulting value is less than zero, + * this function waits for a signal to occur before returning. + * + * @param dsema + * The semaphore. The result of passing NULL in this parameter is undefined. + * + * @param timeout + * When to timeout (see dispatch_time). As a convenience, there are the + * DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants. + * + * @result + * Returns zero on success, or non-zero if the timeout occurred. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +intptr_t +dispatch_semaphore_wait(dispatch_semaphore_t dsema, dispatch_time_t timeout); + +/*! + * @function dispatch_semaphore_signal + * + * @abstract + * Signal (increment) a semaphore. + * + * @discussion + * Increment the counting semaphore. If the previous value was less than zero, + * this function wakes a waiting thread before returning. + * + * @param dsema The counting semaphore. + * The result of passing NULL in this parameter is undefined. + * + * @result + * This function returns non-zero if a thread is woken. Otherwise, zero is + * returned. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +intptr_t +dispatch_semaphore_signal(dispatch_semaphore_t dsema); + +__END_DECLS + +DISPATCH_ASSUME_NONNULL_END + +#endif /* __DISPATCH_SEMAPHORE__ */
\ No newline at end of file diff --git a/lib/libc/include/aarch64-macos-gnu/dispatch/source.h b/lib/libc/include/aarch64-macos-gnu/dispatch/source.h new file mode 100644 index 0000000000..91b23badfd --- /dev/null +++ b/lib/libc/include/aarch64-macos-gnu/dispatch/source.h @@ -0,0 +1,780 @@ +/* + * Copyright (c) 2008-2013 Apple Inc. All rights reserved. + * + * @APPLE_APACHE_LICENSE_HEADER_START@ + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * @APPLE_APACHE_LICENSE_HEADER_END@ + */ + +#ifndef __DISPATCH_SOURCE__ +#define __DISPATCH_SOURCE__ + +#ifndef __DISPATCH_INDIRECT__ +#error "Please #include <dispatch/dispatch.h> instead of this file directly." +#include <dispatch/base.h> // for HeaderDoc +#endif + +#if TARGET_OS_MAC +#include <mach/port.h> +#include <mach/message.h> +#endif + +#if !defined(_WIN32) +#include <sys/signal.h> +#endif + +DISPATCH_ASSUME_NONNULL_BEGIN + +/*! + * @header + * The dispatch framework provides a suite of interfaces for monitoring low- + * level system objects (file descriptors, Mach ports, signals, VFS nodes, etc.) + * for activity and automatically submitting event handler blocks to dispatch + * queues when such activity occurs. + * + * This suite of interfaces is known as the Dispatch Source API. + */ + +/*! + * @typedef dispatch_source_t + * + * @abstract + * Dispatch sources are used to automatically submit event handler blocks to + * dispatch queues in response to external events. + */ +DISPATCH_SOURCE_DECL(dispatch_source); + +__BEGIN_DECLS + +/*! + * @typedef dispatch_source_type_t + * + * @abstract + * Constants of this type represent the class of low-level system object that + * is being monitored by the dispatch source. Constants of this type are + * passed as a parameter to dispatch_source_create() and determine how the + * handle argument is interpreted (i.e. as a file descriptor, mach port, + * signal number, process identifier, etc.), and how the mask argument is + * interpreted. + */ +typedef const struct dispatch_source_type_s *dispatch_source_type_t; + +/*! + * @const DISPATCH_SOURCE_TYPE_DATA_ADD + * @discussion A dispatch source that coalesces data obtained via calls to + * dispatch_source_merge_data(). An ADD is used to coalesce the data. + * The handle is unused (pass zero for now). + * The mask is unused (pass zero for now). + */ +#define DISPATCH_SOURCE_TYPE_DATA_ADD (&_dispatch_source_type_data_add) +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_SOURCE_TYPE_DECL(data_add); + +/*! + * @const DISPATCH_SOURCE_TYPE_DATA_OR + * @discussion A dispatch source that coalesces data obtained via calls to + * dispatch_source_merge_data(). A bitwise OR is used to coalesce the data. + * The handle is unused (pass zero for now). + * The mask is unused (pass zero for now). + */ +#define DISPATCH_SOURCE_TYPE_DATA_OR (&_dispatch_source_type_data_or) +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_SOURCE_TYPE_DECL(data_or); + +/*! + * @const DISPATCH_SOURCE_TYPE_DATA_REPLACE + * @discussion A dispatch source that tracks data obtained via calls to + * dispatch_source_merge_data(). Newly obtained data values replace existing + * data values not yet delivered to the source handler + * + * A data value of zero will cause the source handler to not be invoked. + * + * The handle is unused (pass zero for now). + * The mask is unused (pass zero for now). + */ +#define DISPATCH_SOURCE_TYPE_DATA_REPLACE (&_dispatch_source_type_data_replace) +API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0)) +DISPATCH_SOURCE_TYPE_DECL(data_replace); + +/*! + * @const DISPATCH_SOURCE_TYPE_MACH_SEND + * @discussion A dispatch source that monitors a Mach port for dead name + * notifications (send right no longer has any corresponding receive right). + * The handle is a Mach port with a send or send-once right (mach_port_t). + * The mask is a mask of desired events from dispatch_source_mach_send_flags_t. + */ +#define DISPATCH_SOURCE_TYPE_MACH_SEND (&_dispatch_source_type_mach_send) +API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE() +DISPATCH_SOURCE_TYPE_DECL(mach_send); + +/*! + * @const DISPATCH_SOURCE_TYPE_MACH_RECV + * @discussion A dispatch source that monitors a Mach port for pending messages. + * The handle is a Mach port with a receive right (mach_port_t). + * The mask is a mask of desired events from dispatch_source_mach_recv_flags_t, + * but no flags are currently defined (pass zero for now). + */ +#define DISPATCH_SOURCE_TYPE_MACH_RECV (&_dispatch_source_type_mach_recv) +API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE() +DISPATCH_SOURCE_TYPE_DECL(mach_recv); + +/*! + * @const DISPATCH_SOURCE_TYPE_MEMORYPRESSURE + * @discussion A dispatch source that monitors the system for changes in + * memory pressure condition. + * The handle is unused (pass zero for now). + * The mask is a mask of desired events from + * dispatch_source_memorypressure_flags_t. + */ +#define DISPATCH_SOURCE_TYPE_MEMORYPRESSURE \ + (&_dispatch_source_type_memorypressure) +API_AVAILABLE(macos(10.9), ios(8.0)) DISPATCH_LINUX_UNAVAILABLE() +DISPATCH_SOURCE_TYPE_DECL(memorypressure); + +/*! + * @const DISPATCH_SOURCE_TYPE_PROC + * @discussion A dispatch source that monitors an external process for events + * defined by dispatch_source_proc_flags_t. + * The handle is a process identifier (pid_t). + * The mask is a mask of desired events from dispatch_source_proc_flags_t. + */ +#define DISPATCH_SOURCE_TYPE_PROC (&_dispatch_source_type_proc) +API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE() +DISPATCH_SOURCE_TYPE_DECL(proc); + +/*! + * @const DISPATCH_SOURCE_TYPE_READ + * @discussion A dispatch source that monitors a file descriptor for pending + * bytes available to be read. + * The handle is a file descriptor (int). + * The mask is unused (pass zero for now). + */ +#define DISPATCH_SOURCE_TYPE_READ (&_dispatch_source_type_read) +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_SOURCE_TYPE_DECL(read); + +/*! + * @const DISPATCH_SOURCE_TYPE_SIGNAL + * @discussion A dispatch source that monitors the current process for signals. + * The handle is a signal number (int). + * The mask is unused (pass zero for now). + */ +#define DISPATCH_SOURCE_TYPE_SIGNAL (&_dispatch_source_type_signal) +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_SOURCE_TYPE_DECL(signal); + +/*! + * @const DISPATCH_SOURCE_TYPE_TIMER + * @discussion A dispatch source that submits the event handler block based + * on a timer. + * The handle is unused (pass zero for now). + * The mask specifies which flags from dispatch_source_timer_flags_t to apply. + */ +#define DISPATCH_SOURCE_TYPE_TIMER (&_dispatch_source_type_timer) +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_SOURCE_TYPE_DECL(timer); + +/*! + * @const DISPATCH_SOURCE_TYPE_VNODE + * @discussion A dispatch source that monitors a file descriptor for events + * defined by dispatch_source_vnode_flags_t. + * The handle is a file descriptor (int). + * The mask is a mask of desired events from dispatch_source_vnode_flags_t. + */ +#define DISPATCH_SOURCE_TYPE_VNODE (&_dispatch_source_type_vnode) +API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE() +DISPATCH_SOURCE_TYPE_DECL(vnode); + +/*! + * @const DISPATCH_SOURCE_TYPE_WRITE + * @discussion A dispatch source that monitors a file descriptor for available + * buffer space to write bytes. + * The handle is a file descriptor (int). + * The mask is unused (pass zero for now). + */ +#define DISPATCH_SOURCE_TYPE_WRITE (&_dispatch_source_type_write) +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_SOURCE_TYPE_DECL(write); + +/*! + * @typedef dispatch_source_mach_send_flags_t + * Type of dispatch_source_mach_send flags + * + * @constant DISPATCH_MACH_SEND_DEAD + * The receive right corresponding to the given send right was destroyed. + */ +#define DISPATCH_MACH_SEND_DEAD 0x1 + +typedef unsigned long dispatch_source_mach_send_flags_t; + +/*! + * @typedef dispatch_source_mach_recv_flags_t + * Type of dispatch_source_mach_recv flags + */ +typedef unsigned long dispatch_source_mach_recv_flags_t; + +/*! + * @typedef dispatch_source_memorypressure_flags_t + * Type of dispatch_source_memorypressure flags + * + * @constant DISPATCH_MEMORYPRESSURE_NORMAL + * The system memory pressure condition has returned to normal. + * + * @constant DISPATCH_MEMORYPRESSURE_WARN + * The system memory pressure condition has changed to warning. + * + * @constant DISPATCH_MEMORYPRESSURE_CRITICAL + * The system memory pressure condition has changed to critical. + * + * @discussion + * Elevated memory pressure is a system-wide condition that applications + * registered for this source should react to by changing their future memory + * use behavior, e.g. by reducing cache sizes of newly initiated operations + * until memory pressure returns back to normal. + * NOTE: applications should NOT traverse and discard existing caches for past + * operations when the system memory pressure enters an elevated state, as that + * is likely to trigger VM operations that will further aggravate system memory + * pressure. + */ + +#define DISPATCH_MEMORYPRESSURE_NORMAL 0x01 +#define DISPATCH_MEMORYPRESSURE_WARN 0x02 +#define DISPATCH_MEMORYPRESSURE_CRITICAL 0x04 + +typedef unsigned long dispatch_source_memorypressure_flags_t; + +/*! + * @typedef dispatch_source_proc_flags_t + * Type of dispatch_source_proc flags + * + * @constant DISPATCH_PROC_EXIT + * The process has exited (perhaps cleanly, perhaps not). + * + * @constant DISPATCH_PROC_FORK + * The process has created one or more child processes. + * + * @constant DISPATCH_PROC_EXEC + * The process has become another executable image via + * exec*() or posix_spawn*(). + * + * @constant DISPATCH_PROC_SIGNAL + * A Unix signal was delivered to the process. + */ +#define DISPATCH_PROC_EXIT 0x80000000 +#define DISPATCH_PROC_FORK 0x40000000 +#define DISPATCH_PROC_EXEC 0x20000000 +#define DISPATCH_PROC_SIGNAL 0x08000000 + +typedef unsigned long dispatch_source_proc_flags_t; + +/*! + * @typedef dispatch_source_vnode_flags_t + * Type of dispatch_source_vnode flags + * + * @constant DISPATCH_VNODE_DELETE + * The filesystem object was deleted from the namespace. + * + * @constant DISPATCH_VNODE_WRITE + * The filesystem object data changed. + * + * @constant DISPATCH_VNODE_EXTEND + * The filesystem object changed in size. + * + * @constant DISPATCH_VNODE_ATTRIB + * The filesystem object metadata changed. + * + * @constant DISPATCH_VNODE_LINK + * The filesystem object link count changed. + * + * @constant DISPATCH_VNODE_RENAME + * The filesystem object was renamed in the namespace. + * + * @constant DISPATCH_VNODE_REVOKE + * The filesystem object was revoked. + * + * @constant DISPATCH_VNODE_FUNLOCK + * The filesystem object was unlocked. + */ + +#define DISPATCH_VNODE_DELETE 0x1 +#define DISPATCH_VNODE_WRITE 0x2 +#define DISPATCH_VNODE_EXTEND 0x4 +#define DISPATCH_VNODE_ATTRIB 0x8 +#define DISPATCH_VNODE_LINK 0x10 +#define DISPATCH_VNODE_RENAME 0x20 +#define DISPATCH_VNODE_REVOKE 0x40 +#define DISPATCH_VNODE_FUNLOCK 0x100 + +typedef unsigned long dispatch_source_vnode_flags_t; + +/*! + * @typedef dispatch_source_timer_flags_t + * Type of dispatch_source_timer flags + * + * @constant DISPATCH_TIMER_STRICT + * Specifies that the system should make a best effort to strictly observe the + * leeway value specified for the timer via dispatch_source_set_timer(), even + * if that value is smaller than the default leeway value that would be applied + * to the timer otherwise. A minimal amount of leeway will be applied to the + * timer even if this flag is specified. + * + * CAUTION: Use of this flag may override power-saving techniques employed by + * the system and cause higher power consumption, so it must be used with care + * and only when absolutely necessary. + */ + +#define DISPATCH_TIMER_STRICT 0x1 + +typedef unsigned long dispatch_source_timer_flags_t; + +/*! + * @function dispatch_source_create + * + * @abstract + * Creates a new dispatch source to monitor low-level system objects and auto- + * matically submit a handler block to a dispatch queue in response to events. + * + * @discussion + * Dispatch sources are not reentrant. Any events received while the dispatch + * source is suspended or while the event handler block is currently executing + * will be coalesced and delivered after the dispatch source is resumed or the + * event handler block has returned. + * + * Dispatch sources are created in an inactive state. After creating the + * source and setting any desired attributes (i.e. the handler, context, etc.), + * a call must be made to dispatch_activate() in order to begin event delivery. + * + * Calling dispatch_set_target_queue() on a source once it has been activated + * is not allowed (see dispatch_activate() and dispatch_set_target_queue()). + * + * For backward compatibility reasons, dispatch_resume() on an inactive, + * and not otherwise suspended source has the same effect as calling + * dispatch_activate(). For new code, using dispatch_activate() is preferred. + * + * @param type + * Declares the type of the dispatch source. Must be one of the defined + * dispatch_source_type_t constants. + * + * @param handle + * The underlying system handle to monitor. The interpretation of this argument + * is determined by the constant provided in the type parameter. + * + * @param mask + * A mask of flags specifying which events are desired. The interpretation of + * this argument is determined by the constant provided in the type parameter. + * + * @param queue + * The dispatch queue to which the event handler block will be submitted. + * If queue is DISPATCH_TARGET_QUEUE_DEFAULT, the source will submit the event + * handler block to the default priority global queue. + * + * @result + * The newly created dispatch source. Or NULL if invalid arguments are passed. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT +DISPATCH_NOTHROW +dispatch_source_t +dispatch_source_create(dispatch_source_type_t type, + uintptr_t handle, + uintptr_t mask, + dispatch_queue_t _Nullable queue); + +/*! + * @function dispatch_source_set_event_handler + * + * @abstract + * Sets the event handler block for the given dispatch source. + * + * @param source + * The dispatch source to modify. + * The result of passing NULL in this parameter is undefined. + * + * @param handler + * The event handler block to submit to the source's target queue. + */ +#ifdef __BLOCKS__ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW +void +dispatch_source_set_event_handler(dispatch_source_t source, + dispatch_block_t _Nullable handler); +#endif /* __BLOCKS__ */ + +/*! + * @function dispatch_source_set_event_handler_f + * + * @abstract + * Sets the event handler function for the given dispatch source. + * + * @param source + * The dispatch source to modify. + * The result of passing NULL in this parameter is undefined. + * + * @param handler + * The event handler function to submit to the source's target queue. + * The context parameter passed to the event handler function is the context of + * the dispatch source current at the time the event handler was set. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW +void +dispatch_source_set_event_handler_f(dispatch_source_t source, + dispatch_function_t _Nullable handler); + +/*! + * @function dispatch_source_set_cancel_handler + * + * @abstract + * Sets the cancellation handler block for the given dispatch source. + * + * @discussion + * The cancellation handler (if specified) will be submitted to the source's + * target queue in response to a call to dispatch_source_cancel() once the + * system has released all references to the source's underlying handle and + * the source's event handler block has returned. + * + * IMPORTANT: + * Source cancellation and a cancellation handler are required for file + * descriptor and mach port based sources in order to safely close the + * descriptor or destroy the port. + * Closing the descriptor or port before the cancellation handler is invoked may + * result in a race condition. If a new descriptor is allocated with the same + * value as the recently closed descriptor while the source's event handler is + * still running, the event handler may read/write data to the wrong descriptor. + * + * @param source + * The dispatch source to modify. + * The result of passing NULL in this parameter is undefined. + * + * @param handler + * The cancellation handler block to submit to the source's target queue. + */ +#ifdef __BLOCKS__ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW +void +dispatch_source_set_cancel_handler(dispatch_source_t source, + dispatch_block_t _Nullable handler); +#endif /* __BLOCKS__ */ + +/*! + * @function dispatch_source_set_cancel_handler_f + * + * @abstract + * Sets the cancellation handler function for the given dispatch source. + * + * @discussion + * See dispatch_source_set_cancel_handler() for more details. + * + * @param source + * The dispatch source to modify. + * The result of passing NULL in this parameter is undefined. + * + * @param handler + * The cancellation handler function to submit to the source's target queue. + * The context parameter passed to the event handler function is the current + * context of the dispatch source at the time the handler call is made. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW +void +dispatch_source_set_cancel_handler_f(dispatch_source_t source, + dispatch_function_t _Nullable handler); + +/*! + * @function dispatch_source_cancel + * + * @abstract + * Asynchronously cancel the dispatch source, preventing any further invocation + * of its event handler block. + * + * @discussion + * Cancellation prevents any further invocation of the event handler block for + * the specified dispatch source, but does not interrupt an event handler + * block that is already in progress. + * + * The cancellation handler is submitted to the source's target queue once the + * the source's event handler has finished, indicating it is now safe to close + * the source's handle (i.e. file descriptor or mach port). + * + * See dispatch_source_set_cancel_handler() for more information. + * + * @param source + * The dispatch source to be canceled. + * The result of passing NULL in this parameter is undefined. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_source_cancel(dispatch_source_t source); + +/*! + * @function dispatch_source_testcancel + * + * @abstract + * Tests whether the given dispatch source has been canceled. + * + * @param source + * The dispatch source to be tested. + * The result of passing NULL in this parameter is undefined. + * + * @result + * Non-zero if canceled and zero if not canceled. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE +DISPATCH_NOTHROW +intptr_t +dispatch_source_testcancel(dispatch_source_t source); + +/*! + * @function dispatch_source_get_handle + * + * @abstract + * Returns the underlying system handle associated with this dispatch source. + * + * @param source + * The result of passing NULL in this parameter is undefined. + * + * @result + * The return value should be interpreted according to the type of the dispatch + * source, and may be one of the following handles: + * + * DISPATCH_SOURCE_TYPE_DATA_ADD: n/a + * DISPATCH_SOURCE_TYPE_DATA_OR: n/a + * DISPATCH_SOURCE_TYPE_DATA_REPLACE: n/a + * DISPATCH_SOURCE_TYPE_MACH_SEND: mach port (mach_port_t) + * DISPATCH_SOURCE_TYPE_MACH_RECV: mach port (mach_port_t) + * DISPATCH_SOURCE_TYPE_MEMORYPRESSURE n/a + * DISPATCH_SOURCE_TYPE_PROC: process identifier (pid_t) + * DISPATCH_SOURCE_TYPE_READ: file descriptor (int) + * DISPATCH_SOURCE_TYPE_SIGNAL: signal number (int) + * DISPATCH_SOURCE_TYPE_TIMER: n/a + * DISPATCH_SOURCE_TYPE_VNODE: file descriptor (int) + * DISPATCH_SOURCE_TYPE_WRITE: file descriptor (int) + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE +DISPATCH_NOTHROW +uintptr_t +dispatch_source_get_handle(dispatch_source_t source); + +/*! + * @function dispatch_source_get_mask + * + * @abstract + * Returns the mask of events monitored by the dispatch source. + * + * @param source + * The result of passing NULL in this parameter is undefined. + * + * @result + * The return value should be interpreted according to the type of the dispatch + * source, and may be one of the following flag sets: + * + * DISPATCH_SOURCE_TYPE_DATA_ADD: n/a + * DISPATCH_SOURCE_TYPE_DATA_OR: n/a + * DISPATCH_SOURCE_TYPE_DATA_REPLACE: n/a + * DISPATCH_SOURCE_TYPE_MACH_SEND: dispatch_source_mach_send_flags_t + * DISPATCH_SOURCE_TYPE_MACH_RECV: dispatch_source_mach_recv_flags_t + * DISPATCH_SOURCE_TYPE_MEMORYPRESSURE dispatch_source_memorypressure_flags_t + * DISPATCH_SOURCE_TYPE_PROC: dispatch_source_proc_flags_t + * DISPATCH_SOURCE_TYPE_READ: n/a + * DISPATCH_SOURCE_TYPE_SIGNAL: n/a + * DISPATCH_SOURCE_TYPE_TIMER: dispatch_source_timer_flags_t + * DISPATCH_SOURCE_TYPE_VNODE: dispatch_source_vnode_flags_t + * DISPATCH_SOURCE_TYPE_WRITE: n/a + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE +DISPATCH_NOTHROW +uintptr_t +dispatch_source_get_mask(dispatch_source_t source); + +/*! + * @function dispatch_source_get_data + * + * @abstract + * Returns pending data for the dispatch source. + * + * @discussion + * This function is intended to be called from within the event handler block. + * The result of calling this function outside of the event handler callback is + * undefined. + * + * @param source + * The result of passing NULL in this parameter is undefined. + * + * @result + * The return value should be interpreted according to the type of the dispatch + * source, and may be one of the following: + * + * DISPATCH_SOURCE_TYPE_DATA_ADD: application defined data + * DISPATCH_SOURCE_TYPE_DATA_OR: application defined data + * DISPATCH_SOURCE_TYPE_DATA_REPLACE: application defined data + * DISPATCH_SOURCE_TYPE_MACH_SEND: dispatch_source_mach_send_flags_t + * DISPATCH_SOURCE_TYPE_MACH_RECV: dispatch_source_mach_recv_flags_t + * DISPATCH_SOURCE_TYPE_MEMORYPRESSURE dispatch_source_memorypressure_flags_t + * DISPATCH_SOURCE_TYPE_PROC: dispatch_source_proc_flags_t + * DISPATCH_SOURCE_TYPE_READ: estimated bytes available to read + * DISPATCH_SOURCE_TYPE_SIGNAL: number of signals delivered since + * the last handler invocation + * DISPATCH_SOURCE_TYPE_TIMER: number of times the timer has fired + * since the last handler invocation + * DISPATCH_SOURCE_TYPE_VNODE: dispatch_source_vnode_flags_t + * DISPATCH_SOURCE_TYPE_WRITE: estimated buffer space available + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE +DISPATCH_NOTHROW +uintptr_t +dispatch_source_get_data(dispatch_source_t source); + +/*! + * @function dispatch_source_merge_data + * + * @abstract + * Merges data into a dispatch source of type DISPATCH_SOURCE_TYPE_DATA_ADD, + * DISPATCH_SOURCE_TYPE_DATA_OR or DISPATCH_SOURCE_TYPE_DATA_REPLACE, + * and submits its event handler block to its target queue. + * + * @param source + * The result of passing NULL in this parameter is undefined. + * + * @param value + * The value to coalesce with the pending data using a logical OR or an ADD + * as specified by the dispatch source type. A value of zero has no effect + * and will not result in the submission of the event handler block. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_source_merge_data(dispatch_source_t source, uintptr_t value); + +/*! + * @function dispatch_source_set_timer + * + * @abstract + * Sets a start time, interval, and leeway value for a timer source. + * + * @discussion + * Once this function returns, any pending source data accumulated for the + * previous timer values has been cleared; the next fire of the timer will + * occur at 'start', and every 'interval' nanoseconds thereafter until the + * timer source is canceled. + * + * Any fire of the timer may be delayed by the system in order to improve power + * consumption and system performance. The upper limit to the allowable delay + * may be configured with the 'leeway' argument, the lower limit is under the + * control of the system. + * + * For the initial timer fire at 'start', the upper limit to the allowable + * delay is set to 'leeway' nanoseconds. For the subsequent timer fires at + * 'start' + N * 'interval', the upper limit is MIN('leeway','interval'/2). + * + * The lower limit to the allowable delay may vary with process state such as + * visibility of application UI. If the specified timer source was created with + * a mask of DISPATCH_TIMER_STRICT, the system will make a best effort to + * strictly observe the provided 'leeway' value even if it is smaller than the + * current lower limit. Note that a minimal amount of delay is to be expected + * even if this flag is specified. + * + * The 'start' argument also determines which clock will be used for the timer: + * If 'start' is DISPATCH_TIME_NOW or was created with dispatch_time(3), the + * timer is based on up time (which is obtained from mach_absolute_time() on + * Apple platforms). If 'start' was created with dispatch_walltime(3), the + * timer is based on gettimeofday(3). + * + * Calling this function has no effect if the timer source has already been + * canceled. + * + * @param start + * The start time of the timer. See dispatch_time() and dispatch_walltime() + * for more information. + * + * @param interval + * The nanosecond interval for the timer. Use DISPATCH_TIME_FOREVER for a + * one-shot timer. + * + * @param leeway + * The nanosecond leeway for the timer. + */ +API_AVAILABLE(macos(10.6), ios(4.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_source_set_timer(dispatch_source_t source, + dispatch_time_t start, + uint64_t interval, + uint64_t leeway); + +/*! + * @function dispatch_source_set_registration_handler + * + * @abstract + * Sets the registration handler block for the given dispatch source. + * + * @discussion + * The registration handler (if specified) will be submitted to the source's + * target queue once the corresponding kevent() has been registered with the + * system, following the initial dispatch_resume() of the source. + * + * If a source is already registered when the registration handler is set, the + * registration handler will be invoked immediately. + * + * @param source + * The dispatch source to modify. + * The result of passing NULL in this parameter is undefined. + * + * @param handler + * The registration handler block to submit to the source's target queue. + */ +#ifdef __BLOCKS__ +API_AVAILABLE(macos(10.7), ios(4.3)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW +void +dispatch_source_set_registration_handler(dispatch_source_t source, + dispatch_block_t _Nullable handler); +#endif /* __BLOCKS__ */ + +/*! + * @function dispatch_source_set_registration_handler_f + * + * @abstract + * Sets the registration handler function for the given dispatch source. + * + * @discussion + * See dispatch_source_set_registration_handler() for more details. + * + * @param source + * The dispatch source to modify. + * The result of passing NULL in this parameter is undefined. + * + * @param handler + * The registration handler function to submit to the source's target queue. + * The context parameter passed to the registration handler function is the + * current context of the dispatch source at the time the handler call is made. + */ +API_AVAILABLE(macos(10.7), ios(4.3)) +DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW +void +dispatch_source_set_registration_handler_f(dispatch_source_t source, + dispatch_function_t _Nullable handler); + +__END_DECLS + +DISPATCH_ASSUME_NONNULL_END + +#endif
\ No newline at end of file diff --git a/lib/libc/include/aarch64-macos-gnu/dispatch/workloop.h b/lib/libc/include/aarch64-macos-gnu/dispatch/workloop.h new file mode 100644 index 0000000000..7d27b1f207 --- /dev/null +++ b/lib/libc/include/aarch64-macos-gnu/dispatch/workloop.h @@ -0,0 +1,163 @@ +/* + * Copyright (c) 2017-2019 Apple Inc. All rights reserved. + * + * @APPLE_APACHE_LICENSE_HEADER_START@ + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * @APPLE_APACHE_LICENSE_HEADER_END@ + */ + +#ifndef __DISPATCH_WORKLOOP__ +#define __DISPATCH_WORKLOOP__ + +#ifndef __DISPATCH_INDIRECT__ +#error "Please #include <dispatch/dispatch.h> instead of this file directly." +#include <dispatch/base.h> // for HeaderDoc +#endif + +DISPATCH_ASSUME_NONNULL_BEGIN + +__BEGIN_DECLS + +/*! + * @typedef dispatch_workloop_t + * + * @abstract + * Dispatch workloops invoke workitems submitted to them in priority order. + * + * @discussion + * A dispatch workloop is a flavor of dispatch_queue_t that is a priority + * ordered queue (using the QOS class of the submitted workitems as the + * ordering). + * + * Between each workitem invocation, the workloop will evaluate whether higher + * priority workitems have since been submitted, either directly to the + * workloop or to any queues that target the workloop, and execute these first. + * + * Serial queues targeting a workloop maintain FIFO execution of their + * workitems. However, the workloop may reorder workitems submitted to + * independent serial queues targeting it with respect to each other, + * based on their priorities, while preserving FIFO execution with respect to + * each serial queue. + * + * A dispatch workloop is a "subclass" of dispatch_queue_t which can be passed + * to all APIs accepting a dispatch queue, except for functions from the + * dispatch_sync() family. dispatch_async_and_wait() must be used for workloop + * objects. Functions from the dispatch_sync() family on queues targeting + * a workloop are still permitted but discouraged for performance reasons. + */ +DISPATCH_DECL_SUBCLASS(dispatch_workloop, dispatch_queue); + +/*! + * @function dispatch_workloop_create + * + * @abstract + * Creates a new dispatch workloop to which workitems may be submitted. + * + * @param label + * A string label to attach to the workloop. + * + * @result + * The newly created dispatch workloop. + */ +API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) +DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT +DISPATCH_NOTHROW +dispatch_workloop_t +dispatch_workloop_create(const char *_Nullable label); + +/*! + * @function dispatch_workloop_create_inactive + * + * @abstract + * Creates a new inactive dispatch workloop that can be setup and then + * activated. + * + * @discussion + * Creating an inactive workloop allows for it to receive further configuration + * before it is activated, and workitems can be submitted to it. + * + * Submitting workitems to an inactive workloop is undefined and will cause the + * process to be terminated. + * + * @param label + * A string label to attach to the workloop. + * + * @result + * The newly created dispatch workloop. + */ +API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) +DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT +DISPATCH_NOTHROW +dispatch_workloop_t +dispatch_workloop_create_inactive(const char *_Nullable label); + +/*! + * @function dispatch_workloop_set_autorelease_frequency + * + * @abstract + * Sets the autorelease frequency of the workloop. + * + * @discussion + * See dispatch_queue_attr_make_with_autorelease_frequency(). + * The default policy for a workloop is + * DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM. + * + * @param workloop + * The dispatch workloop to modify. + * + * This workloop must be inactive, passing an activated object is undefined + * and will cause the process to be terminated. + * + * @param frequency + * The requested autorelease frequency. + */ +API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_workloop_set_autorelease_frequency(dispatch_workloop_t workloop, + dispatch_autorelease_frequency_t frequency); + +/*! + * @function dispatch_workloop_set_os_workgroup + * + * @abstract + * Associates an os_workgroup_t with the specified dispatch workloop. + * + * The worker thread will be a member of the specified os_workgroup_t while executing + * work items submitted to the workloop. + * + * @param workloop + * The dispatch workloop to modify. + * + * This workloop must be inactive, passing an activated object is undefined + * and will cause the process to be terminated. + * + * @param workgroup + * The workgroup to associate with this workloop. + * + * The workgroup specified is retained and the previously associated workgroup + * (if any) is released. + */ +API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0)) +DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW +void +dispatch_workloop_set_os_workgroup(dispatch_workloop_t workloop, + os_workgroup_t workgroup); + +__END_DECLS + +DISPATCH_ASSUME_NONNULL_END + +#endif
\ No newline at end of file |