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
 29DISPATCH_ASSUME_NONNULL_BEGIN
 30DISPATCH_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 */
 63API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 64DISPATCH_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 */
 78API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 79DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 80DISPATCH_NOTHROW
 81DISPATCH_REFINED_FOR_SWIFT
 82dispatch_workloop_t
 83dispatch_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 */
105API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
106DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
107DISPATCH_NOTHROW
108DISPATCH_REFINED_FOR_SWIFT DISPATCH_SWIFT_NAME(DispatchWorkloop.init(__label:))
109dispatch_workloop_t
110dispatch_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 */
132API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
133DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
134DISPATCH_REFINED_FOR_SWIFT
135void
136dispatch_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  */
164API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0))
165DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
166DISPATCH_REFINED_FOR_SWIFT
167void
168dispatch_workloop_set_os_workgroup(dispatch_workloop_t workloop,
169		os_workgroup_t workgroup);
170
171__END_DECLS
172
173DISPATCH_ASSUME_ABI_SINGLE_END
174DISPATCH_ASSUME_NONNULL_END
175
176#endif