1/*
2 * Copyright (c) 2019-2019 Apple Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28
29#ifndef _IOKIT_UIODISPATCHQUEUE_H
30#define _IOKIT_UIODISPATCHQUEUE_H
31
32#include <DriverKit/OSObject.iig>
33#include <DriverKit/OSAction.iig>
34#include <DriverKit/IODispatchSource.iig>
35
36typedef int (*IODispatchLogFunction)(const char *format, ...);
37typedef void (^IODispatchBlock)(void);
38typedef void (*IODispatchFunction)(void * context);
39typedef kern_return_t (^IODispatchAction)(void);
40
41typedef void (^IODispatchQueueCancelHandler)(void);
42
43
44// options for Create()
45enum {
46	kIODispatchQueueReentrant              = 0x00000001,
47	kIODispatchQueueMethodsNotSynchronized = 0x00000002,
48};
49
50// options for WakeupWithOptions()
51enum {
52	kIODispatchQueueWakeupAll              = 0x00000001,
53};
54
55// options for SleepWithDeadline()
56enum {
57	// Sleep on an event which other threads are still waiting on, but has already been signaled
58	kIODispatchQueueSleepReuseEvent        = 0x00000100,
59};
60
61/*!
62 * @class IODispatchQueue
63 *
64 * @abstract
65 * IODispatchQueue provides a queue for ordered execution of blocks.
66 *
67 * @discussion
68 * All blocks submitted to dispatch queues are dequeued in FIFO order.
69 * By default the queue is serial and will execute one block at a time.
70 */
71
72class NATIVE KERNEL IODispatchQueue : public OSObject
73{
74public:
75    /*!
76     * @brief       Creates a new dispatch queue object.
77     * @discussion  Creates a new dispatch queue object. All queues are currently serial, executing one block at time
78     *              FIFO order. The new object has retain count 1 and should be released by the caller.
79     * @param       options
80                    kIODispatchQueueReentrant Creates a queue that allows release with the Sleep
81                    method, so that other threads and callers may acquire the queue.
82     * @param       priority No priorities are currently defined, pass zero.
83     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
84     */
85	static kern_return_t
86	Create(
87		const IODispatchQueueName name,
88		uint64_t                  options,
89		uint64_t                  priority,
90		IODispatchQueue        ** queue) LOCAL;
91
92	virtual bool
93	init() override;
94
95	virtual void
96	free() override;
97
98    /*!
99     * @brief       Determines if the current thread is running on the queue.
100     * @discussion  Determines if the current thread is running on the queue, including if the queue invoked a
101     *              second queue (ie. OnQueue can return true for more than one queue in a given context.)
102     * @return      bool true if current thread is running on this queue.
103     */
104	bool
105	OnQueue() LOCALONLY;
106
107    /*!
108     * @brief       Return the name the queue was created with.
109     * @discussion  Returns a pointer to the queues name. Only valid while the queue is retained.
110     * @return      C-string pointer in the queues internal storage.
111     */
112	const char *
113	GetName() LOCALONLY;
114
115    /*!
116     * @brief       Stop the queue from executing futher work.
117     * @discussion  Stops the queue from dequeuing work, and on completion of any block currently being executed,
118     *              invokes a callback block. Canceling is asynchronous.
119     * @param       handler Block that will executed when the queue has completed any inflight work
120     *              and will not execute further work.
121     * @return      C-string pointer in the queues internal storage.
122     */
123	kern_return_t
124	Cancel(IODispatchQueueCancelHandler handler) LOCALONLY;
125
126    /*!
127     * @brief       Schedule a block to be executed on the queue asynchronously.
128     * @discussion  Schedules work to be done on the queue without waiting for it to complete. The queue will be
129     *              retained until the block completes.
130     * @param       block Block that will executed on the queue, not in the context of the caller.
131     */
132	void
133	DispatchAsync(IODispatchBlock block) LOCALONLY;
134
135    /*!
136     * @brief       C-function callback version of DispatchAsync.
137	 */
138	void
139	DispatchAsync_f(void * context, IODispatchFunction function) LOCALONLY;
140
141    /*!
142     * @brief       Schedule a block to be executed concurrently & asynchronously.
143     * @discussion  Schedules work to be done on the queue without waiting for it to complete, and
144     *              concurrently with other blocks executed with DispatchConcurrent. The queue will be
145     *              retained until the block completes. May only be used with a queue created with
146     *              the kIODispatchQueueReentrant option.
147     * @param       block Block that will executed on the queue, not in the context of the caller.
148     */
149	void
150	DispatchConcurrent(IODispatchBlock block) LOCALONLY;
151
152    /*!
153     * @brief       C-function callback version of DispatchConcurrent.
154	 */
155	void
156	DispatchConcurrent_f(void * context, IODispatchFunction function) LOCALONLY;
157
158    /*!
159     * @brief       Execute a block on the queue synchronously.
160     * @discussion  Execute a block on the queue synchronously.
161     * @param       block Block that will executed on the queue.
162     */
163	void
164	DispatchSync(IODispatchBlock block) LOCALONLY;
165
166    /*!
167     * @brief       C-function callback version of DispatchSync.
168	 */
169	void
170	DispatchSync_f(void * context, IODispatchFunction function) LOCALONLY;
171
172    /*!
173     * @brief       Log the current execution context with respect to any queues the current thread holds.
174     * @param       output printf like output function. The address of IOLog is suitable to be used.
175	 */
176	static void
177	Log(const char * message, IODispatchLogFunction output) LOCALONLY;
178
179    /*!
180     * @brief       Version of DispatchSync that returns a kern_return_t status.
181	 */
182	kern_return_t
183	RunAction(IODispatchAction action) LOCALONLY;
184
185    /*!
186     * @brief       Put a thread that is currently running the queue to sleep, releasing the queue.
187     * @discussion  Put a thread to sleep waiting for an event but release the queue first.
188     *              In all cases (signal, timeout or error), the caller resumes running on the queue.
189	 *              The caller must be currently running on the queue to call Sleep().
190     * @param       event A unique token matching one later passed to Wakeup().
191     * @param       options Pass one of the kIOTimerClock* options to specify the timebase for the
192     *              deadline, or zero for no timeout.
193     * @param       deadline Clock deadline to timeout the sleep.
194     * @return 		kIOReturnSuccess  or kIOReturnTimeout
195     */
196	kern_return_t
197	SleepWithDeadline(void * event, uint64_t options, uint64_t deadline) LOCALONLY;
198
199    /*!
200     * @brief       Put a thread that is currently running the queue to sleep, releasing the queue.
201     * @discussion  Put a thread to sleep waiting for an event but release the queue first.
202     *              In all cases (signal, timeout or error), the caller resumes running on the queue.
203	 *              The caller must be currently running on the queue to call Sleep().
204     * @param       event A unique token matching one later passed to Wakeup().
205     * @param       timeout Clock delay to timeout the sleep.
206     * @return 		kIOReturnSuccess  or kIOReturnTimeout
207     */
208	kern_return_t
209	SleepWithTimeout(void * event, uint64_t timeout) LOCALONLY;
210
211    /*!
212     * @brief       Synonym for SleepWithTimeout()
213     */
214	kern_return_t
215	Sleep(void * event, uint64_t timeout) LOCALONLY;
216
217    /*!
218     * @brief       Wakes a thread that is blocked in Sleep().
219     * @discussion  Signals a thread that gave up the queue with Sleep() to continue running.
220	 *              The caller must be currently running on the queue.
221     * @param       event A unique token matching one passed to Sleep().
222     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
223     */
224	kern_return_t
225	Wakeup(void * event) LOCALONLY;
226
227    /*!
228     * @brief       Wakes a thread that is blocked in Sleep().
229     * @discussion  Signals a thread that gave up the queue with Sleep() to continue running.
230	 *              The caller must be currently running on the queue.
231     * @param       event A unique token matching one passed to Sleep().
232     * @param       options
233					kIODispatchQueueWakeupAll wake all threads waiting in Sleep().
234					The default is to wake only one of any waiting threads.
235     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
236     */
237	kern_return_t
238	WakeupWithOptions(void * event, uint64_t options) LOCALONLY;
239};
240
241#if DRIVERKIT_PRIVATE
242class EXTENDS (IODispatchQueue) IODispatchQueuePrivate
243{
244	virtual kern_return_t
245	SetPort(
246		mach_port_t port PORTMAKESEND);
247};
248#endif
249
250#endif /* ! _IOKIT_UIODISPATCH_H */
251