| /* |
| * Copyright (c) 2017-2018 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@ |
| */ |
| |
| /* |
| * IMPORTANT: This header file describes INTERNAL interfaces to libdispatch |
| * which are subject to change in future releases of Mac OS X. Any applications |
| * relying on these interfaces WILL break. |
| */ |
| |
| #ifndef __DISPATCH_WORKLOOP_PRIVATE__ |
| #define __DISPATCH_WORKLOOP_PRIVATE__ |
| |
| #ifndef __DISPATCH_INDIRECT__ |
| #error "Please #include <dispatch/private.h> instead of this file directly." |
| #include <dispatch/base.h> // for HeaderDoc |
| #endif |
| |
| /******************************************************************************\ |
| * |
| * THIS FILE IS AN IN-PROGRESS INTERFACE THAT IS SUBJECT TO CHANGE |
| * |
| \******************************************************************************/ |
| |
| 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 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. |
| * |
| * 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. |
| */ |
| #if defined(__DISPATCH_BUILDING_DISPATCH__) && !defined(__OBJC__) |
| typedef struct dispatch_workloop_s *dispatch_workloop_t; |
| #else |
| DISPATCH_DECL_SUBCLASS(dispatch_workloop, dispatch_queue); |
| #endif |
| |
| /*! |
| * @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); |
| |
| DISPATCH_ENUM(dispatch_workloop_param_flags, uint64_t, |
| DISPATCH_WORKLOOP_NONE DISPATCH_ENUM_API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) = 0x0, |
| DISPATCH_WORKLOOP_FIXED_PRIORITY DISPATCH_ENUM_API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) = 0x1, |
| ); |
| |
| /*! |
| * @function dispatch_workloop_set_qos_class_floor |
| * |
| * @abstract |
| * Sets the QOS class floor of a workloop. |
| * |
| * @discussion |
| * See dispatch_set_qos_class_floor(). |
| * |
| * This function is strictly equivalent to dispatch_set_qos_class_floor() but |
| * allows to pass extra flags. |
| * |
| * Using both dispatch_workloop_set_scheduler_priority() and |
| * dispatch_set_qos_class_floor() or dispatch_workloop_set_qos_class_floor() |
| * is undefined and will cause the process to be terminated. |
| * |
| * @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. |
| */ |
| 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_qos_class_floor(dispatch_workloop_t workloop, |
| dispatch_qos_class_t qos, int relpri, dispatch_workloop_param_flags_t flags); |
| |
| /*! |
| * @function dispatch_workloop_set_scheduler_priority |
| * |
| * @abstract |
| * Sets the scheduler priority for a dispatch workloop. |
| * |
| * @discussion |
| * This sets the scheduler priority of the threads that the runtime will bring |
| * up to service this workloop. |
| * |
| * QOS propagation still functions on these workloops, but its effect on the |
| * priority of the thread brought up to service this workloop is ignored. |
| * |
| * Using both dispatch_workloop_set_scheduler_priority() and |
| * dispatch_set_qos_class_floor() or dispatch_workloop_set_qos_class_floor() |
| * is undefined and will cause the process to be terminated. |
| * |
| * @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. |
| */ |
| 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_scheduler_priority(dispatch_workloop_t workloop, |
| int priority, dispatch_workloop_param_flags_t flags); |
| |
| /*! |
| * @function dispatch_workloop_set_cpupercent |
| * |
| * @abstract |
| * Sets the cpu percent and refill attributes for a dispatch workloop. |
| * |
| * @discussion |
| * This should only used if the workloop was also setup with the |
| * DISPATCH_WORKLOOP_FIXED_PRIORITY flag as a safe guard against |
| * busy loops that could starve the rest of the system forever. |
| * |
| * If DISPATCH_WORKLOOP_FIXED_PRIORITY wasn't passed, using this function is |
| * undefined and will cause the process to be terminated. |
| * |
| * @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. |
| */ |
| 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_cpupercent(dispatch_workloop_t workloop, uint8_t percent, |
| uint32_t refillms); |
| |
| /*! |
| * @function dispatch_workloop_is_current() |
| * |
| * @abstract |
| * Returns whether the current thread has been made by the runtime to service |
| * this workloop. |
| * |
| * @discussion |
| * Note that when using <code>dispatch_async_and_wait(workloop, ^{ ... })</code> |
| * then <code>workloop</code> will be seen as the "current" one by the submitted |
| * workitem, but that is not the case when using dispatch_sync() on a queue |
| * targeting the workloop. |
| */ |
| API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) |
| DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW |
| bool |
| dispatch_workloop_is_current(dispatch_workloop_t workloop); |
| |
| /*! |
| * @function dispatch_workloop_copy_current() |
| * |
| * @abstract |
| * Returns a copy of the workoop that is being serviced on the calling thread |
| * if any. |
| * |
| * @discussion |
| * If the thread is not a workqueue thread, or is not servicing a dispatch |
| * workloop, then NULL is returned. |
| * |
| * This returns a retained object that must be released with dispatch_release(). |
| */ |
| API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) |
| DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED DISPATCH_NOTHROW |
| dispatch_workloop_t _Nullable |
| dispatch_workloop_copy_current(void); |
| |
| // Equivalent to dispatch_workloop_set_qos_class_floor(workoop, qos, 0, flags) |
| API_DEPRECATED_WITH_REPLACEMENT("dispatch_workloop_set_qos_class_floor", |
| macos(10.14,10.14), ios(12.0,12.0), tvos(12.0,12.0), watchos(5.0,5.0)) |
| DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW |
| void |
| dispatch_workloop_set_qos_class(dispatch_workloop_t workloop, |
| dispatch_qos_class_t qos, dispatch_workloop_param_flags_t flags); |
| |
| API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) |
| DISPATCH_EXPORT DISPATCH_NOTHROW |
| bool |
| _dispatch_workloop_should_yield_4NW(void); |
| |
| /*! |
| * @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); |
| |
| /*! |
| * @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). |
| * |
| * @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). |
| * |
| * @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); |
| |
| __END_DECLS |
| |
| DISPATCH_ASSUME_NONNULL_END |
| |
| #endif |