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/*! 56 * @class IODispatchQueue 57 * 58 * @abstract 59 * IODispatchQueue provides a queue for ordered execution of blocks. 60 * 61 * @discussion 62 * All blocks submitted to dispatch queues are dequeued in FIFO order. 63 * By default the queue is serial and will execute one block at a time. 64 */ 65 66class NATIVE KERNEL IODispatchQueue : public OSObject 67{ 68public: 69 /*! 70 * @brief Creates a new dispatch queue object. 71 * @discussion Creates a new dispatch queue object. All queues are currently serial, executing one block at time 72 * FIFO order. The new object has retain count 1 and should be released by the caller. 73 * @param options 74 kIODispatchQueueReentrant Creates a queue that allows release with the Sleep 75 method, so that other threads and callers may acquire the queue. 76 * @param priority No priorities are currently defined, pass zero. 77 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 78 */ 79 static kern_return_t 80 Create( 81 const IODispatchQueueName name, 82 uint64_t options, 83 uint64_t priority, 84 IODispatchQueue ** queue) LOCAL; 85 86 virtual bool 87 init() override; 88 89 virtual void 90 free() override; 91 92 /*! 93 * @brief Determines if the current thread is running on the queue. 94 * @discussion Determines if the current thread is running on the queue, including if the queue invoked a 95 * second queue (ie. OnQueue can return true for more than one queue in a given context.) 96 * @return bool true if current thread is running on this queue. 97 */ 98 bool 99 OnQueue() LOCALONLY; 100 101 /*! 102 * @brief Return the name the queue was created with. 103 * @discussion Returns a pointer to the queues name. Only valid while the queue is retained. 104 * @return C-string pointer in the queues internal storage. 105 */ 106 const char * 107 GetName() LOCALONLY; 108 109 /*! 110 * @brief Stop the queue from executing futher work. 111 * @discussion Stops the queue from dequeuing work, and on completion of any block currently being executed, 112 * invokes a callback block. Canceling is asynchronous. 113 * @param handler Block that will executed when the queue has completed any inflight work 114 * and will not execute further work. 115 * @return C-string pointer in the queues internal storage. 116 */ 117 kern_return_t 118 Cancel(IODispatchQueueCancelHandler handler) LOCALONLY; 119 120 /*! 121 * @brief Schedule a block to be executed on the queue asynchronously. 122 * @discussion Schedules work to be done on the queue without waiting for it to complete. The queue will be 123 * retained until the block completes. 124 * @param block Block that will executed on the queue, not in the context of the caller. 125 */ 126 void 127 DispatchAsync(IODispatchBlock block) LOCALONLY; 128 129 /*! 130 * @brief C-function callback version of DispatchAsync. 131 */ 132 void 133 DispatchAsync_f(void * context, IODispatchFunction function) LOCALONLY; 134 135 /*! 136 * @brief Schedule a block to be executed concurrently & asynchronously. 137 * @discussion Schedules work to be done on the queue without waiting for it to complete, and 138 * concurrently with other blocks executed with DispatchConcurrent. The queue will be 139 * retained until the block completes. May only be used with a queue created with 140 * the kIODispatchQueueReentrant option. 141 * @param block Block that will executed on the queue, not in the context of the caller. 142 */ 143 void 144 DispatchConcurrent(IODispatchBlock block) LOCALONLY; 145 146 /*! 147 * @brief C-function callback version of DispatchConcurrent. 148 */ 149 void 150 DispatchConcurrent_f(void * context, IODispatchFunction function) LOCALONLY; 151 152 /*! 153 * @brief Execute a block on the queue synchronously. 154 * @discussion Execute a block on the queue synchronously. 155 * @param block Block that will executed on the queue. 156 */ 157 void 158 DispatchSync(IODispatchBlock block) LOCALONLY; 159 160 /*! 161 * @brief C-function callback version of DispatchSync. 162 */ 163 void 164 DispatchSync_f(void * context, IODispatchFunction function) LOCALONLY; 165 166 /*! 167 * @brief Log the current execution context with respect to any queues the current thread holds. 168 * @param output printf like output function. The address of IOLog is suitable to be used. 169 */ 170 static void 171 Log(const char * message, IODispatchLogFunction output) LOCALONLY; 172 173 /*! 174 * @brief Version of DispatchSync that returns a kern_return_t status. 175 */ 176 kern_return_t 177 RunAction(IODispatchAction action) LOCALONLY; 178 179 /*! 180 * @brief Put a thread that is currently running the queue to sleep, releasing the queue. 181 * @discussion Put a thread to sleep waiting for an event but release the queue first. 182 * In all cases (signal, timeout or error), the caller resumes running on the queue. 183 * The caller must be currently running on the queue to call Sleep(). 184 * @param event A unique token matching one later passed to Wakeup(). 185 * @param options Pass one of the kIOTimerClock* options to specify the timebase for the 186 * deadline, or zero for no timeout. 187 * @param deadline Clock deadline to timeout the sleep. 188 * @return kIOReturnSuccess or kIOReturnTimeout 189 */ 190 kern_return_t 191 SleepWithDeadline(void * event, uint64_t options, uint64_t deadline) LOCALONLY; 192 193 /*! 194 * @brief Put a thread that is currently running the queue to sleep, releasing the queue. 195 * @discussion Put a thread to sleep waiting for an event but release the queue first. 196 * In all cases (signal, timeout or error), the caller resumes running on the queue. 197 * The caller must be currently running on the queue to call Sleep(). 198 * @param event A unique token matching one later passed to Wakeup(). 199 * @param timeout Clock delay to timeout the sleep. 200 * @return kIOReturnSuccess or kIOReturnTimeout 201 */ 202 kern_return_t 203 SleepWithTimeout(void * event, uint64_t timeout) LOCALONLY; 204 205 /*! 206 * @brief Synonym for SleepWithTimeout() 207 */ 208 kern_return_t 209 Sleep(void * event, uint64_t timeout) LOCALONLY; 210 211 /*! 212 * @brief Wakes a thread that is blocked in Sleep(). 213 * @discussion Signals a thread that gave up the queue with Sleep() to continue running. 214 * The caller must be currently running on the queue. 215 * @param event A unique token matching one passed to Sleep(). 216 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 217 */ 218 kern_return_t 219 Wakeup(void * event) LOCALONLY; 220 221 /*! 222 * @brief Wakes a thread that is blocked in Sleep(). 223 * @discussion Signals a thread that gave up the queue with Sleep() to continue running. 224 * The caller must be currently running on the queue. 225 * @param event A unique token matching one passed to Sleep(). 226 * @param options 227 kIODispatchQueueWakeupAll wake all threads waiting in Sleep(). 228 The default is to wake only one of any waiting threads. 229 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 230 */ 231 kern_return_t 232 WakeupWithOptions(void * event, uint64_t options) LOCALONLY; 233}; 234 235#if DRIVERKIT_PRIVATE 236class EXTENDS (IODispatchQueue) IODispatchQueuePrivate 237{ 238 virtual kern_return_t 239 SetPort( 240 mach_port_t port PORTMAKESEND); 241}; 242#endif 243 244#endif /* ! _IOKIT_UIODISPATCH_H */ 245