workloop.h (5967B) - Raw
1 /* 2 * Copyright (c) 2017-2019 Apple Inc. All rights reserved. 3 * 4 * @APPLE_APACHE_LICENSE_HEADER_START@ 5 * 6 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 * 18 * @APPLE_APACHE_LICENSE_HEADER_END@ 19 */ 20 21 #ifndef __DISPATCH_WORKLOOP__ 22 #define __DISPATCH_WORKLOOP__ 23 24 #ifndef __DISPATCH_INDIRECT__ 25 #error "Please #include <dispatch/dispatch.h> instead of this file directly." 26 #include <dispatch/base.h> // for HeaderDoc 27 #endif 28 29 DISPATCH_ASSUME_NONNULL_BEGIN 30 DISPATCH_ASSUME_ABI_SINGLE_BEGIN 31 32 __BEGIN_DECLS 33 34 /*! 35 * @typedef dispatch_workloop_t 36 * 37 * @abstract 38 * Dispatch workloops invoke workitems submitted to them in priority order. 39 * 40 * @discussion 41 * A dispatch workloop is a flavor of dispatch_queue_t that is a priority 42 * ordered queue (using the QOS class of the submitted workitems as the 43 * ordering). Dispatch workloops are an exclusion context and it is guaranteed 44 * that only one work item submitted to the dispatch workloop will be invoked at 45 * a time. 46 * 47 * Between each workitem invocation, the workloop will evaluate whether higher 48 * priority workitems have since been submitted, either directly to the 49 * workloop or to any queues that target the workloop, and execute these first. 50 * 51 * Serial queues targeting a workloop maintain FIFO execution of their 52 * workitems. However, the workloop may reorder workitems submitted to 53 * independent serial queues targeting it with respect to each other, 54 * based on their priorities, while preserving FIFO execution with respect to 55 * each serial queue. 56 * 57 * A dispatch workloop is a "subclass" of dispatch_queue_t which can be passed 58 * to all APIs accepting a dispatch queue, except for functions from the 59 * dispatch_sync() family. dispatch_async_and_wait() must be used for workloop 60 * objects. Functions from the dispatch_sync() family on queues targeting 61 * a workloop are still permitted but discouraged for performance reasons. 62 */ 63 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) 64 DISPATCH_DECL_SERIAL_EXECUTOR_SWIFT(dispatch_workloop, DispatchWorkloop); 65 66 /*! 67 * @function dispatch_workloop_create 68 * 69 * @abstract 70 * Creates a new dispatch workloop to which workitems may be submitted. 71 * 72 * @param label 73 * A string label to attach to the workloop. 74 * 75 * @result 76 * The newly created dispatch workloop. 77 */ 78 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) 79 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT 80 DISPATCH_NOTHROW 81 DISPATCH_REFINED_FOR_SWIFT 82 dispatch_workloop_t 83 dispatch_workloop_create(const char *DISPATCH_UNSAFE_INDEXABLE _Nullable label); 84 85 /*! 86 * @function dispatch_workloop_create_inactive 87 * 88 * @abstract 89 * Creates a new inactive dispatch workloop that can be setup and then 90 * activated. 91 * 92 * @discussion 93 * Creating an inactive workloop allows for it to receive further configuration 94 * before it is activated, and workitems can be submitted to it. 95 * 96 * Submitting workitems to an inactive workloop is undefined and will cause the 97 * process to be terminated. 98 * 99 * @param label 100 * A string label to attach to the workloop. 101 * 102 * @result 103 * The newly created dispatch workloop. 104 */ 105 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) 106 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT 107 DISPATCH_NOTHROW 108 DISPATCH_REFINED_FOR_SWIFT DISPATCH_SWIFT_NAME(DispatchWorkloop.init(__label:)) 109 dispatch_workloop_t 110 dispatch_workloop_create_inactive(const char *DISPATCH_UNSAFE_INDEXABLE _Nullable label); 111 112 /*! 113 * @function dispatch_workloop_set_autorelease_frequency 114 * 115 * @abstract 116 * Sets the autorelease frequency of the workloop. 117 * 118 * @discussion 119 * See dispatch_queue_attr_make_with_autorelease_frequency(). 120 * The default policy for a workloop is 121 * DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM. 122 * 123 * @param workloop 124 * The dispatch workloop to modify. 125 * 126 * This workloop must be inactive, passing an activated object is undefined 127 * and will cause the process to be terminated. 128 * 129 * @param frequency 130 * The requested autorelease frequency. 131 */ 132 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) 133 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW 134 DISPATCH_REFINED_FOR_SWIFT 135 void 136 dispatch_workloop_set_autorelease_frequency(dispatch_workloop_t workloop, 137 dispatch_autorelease_frequency_t frequency); 138 139 /*! 140 * @function dispatch_workloop_set_os_workgroup 141 * 142 * @abstract 143 * Associates an os_workgroup_t with the specified dispatch workloop. 144 * 145 * The worker thread will be a member of the specified os_workgroup_t while executing 146 * work items submitted to the workloop. 147 * 148 * Using both dispatch_workloop_set_scheduler_priority() and 149 * dispatch_workloop_set_os_workgroup() will prefer scheduling policies 150 * from the workgroup, if they exist. 151 * 152 * @param workloop 153 * The dispatch workloop to modify. 154 * 155 * This workloop must be inactive, passing an activated object is undefined 156 * and will cause the process to be terminated. 157 * 158 * @param workgroup 159 * The workgroup to associate with this workloop. 160 * 161 * The workgroup specified is retained and the previously associated workgroup 162 * (if any) is released. 163 */ 164 API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0)) 165 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW 166 DISPATCH_REFINED_FOR_SWIFT 167 void 168 dispatch_workloop_set_os_workgroup(dispatch_workloop_t workloop, 169 os_workgroup_t workgroup); 170 171 __END_DECLS 172 173 DISPATCH_ASSUME_ABI_SINGLE_END 174 DISPATCH_ASSUME_NONNULL_END 175 176 #endif