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#ifdef __APPLE__
140/*!
141 * @function dispatch_workloop_set_os_workgroup
142 *
143 * @abstract
144 * Associates an os_workgroup_t with the specified dispatch workloop.
145 *
146 * The worker thread will be a member of the specified os_workgroup_t while executing
147 * work items submitted to the workloop.
148 *
149 * Using both dispatch_workloop_set_scheduler_priority() and
150 * dispatch_workloop_set_os_workgroup() will prefer scheduling policies
151 * from the workgroup, if they exist.
152 *
153 * @param workloop
154 * The dispatch workloop to modify.
155 *
156 * This workloop must be inactive, passing an activated object is undefined
157 * and will cause the process to be terminated.
158 *
159 * @param workgroup
160 * The workgroup to associate with this workloop.
161 *
162 * The workgroup specified is retained and the previously associated workgroup
163 * (if any) is released.
164 */
165API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0))
166DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
167DISPATCH_REFINED_FOR_SWIFT
168void
169dispatch_workloop_set_os_workgroup(dispatch_workloop_t workloop,
170 os_workgroup_t workgroup);
171#endif
172
173__END_DECLS
174
175DISPATCH_ASSUME_ABI_SINGLE_END
176DISPATCH_ASSUME_NONNULL_END
177
178#endif