/*
* Copyright (c) 2019-2019 Apple Inc. All rights reserved.
*
* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
*
* This file contains Original Code and/or Modifications of Original Code
* as defined in and that are subject to the Apple Public Source License
* Version 2.0 (the 'License'). You may not use this file except in
* compliance with the License. The rights granted to you under the License
* may not be used to create, or enable the creation or redistribution of,
* unlawful or unlicensed copies of an Apple operating system, or to
* circumvent, violate, or enable the circumvention or violation of, any
* terms of an Apple operating system software license agreement.
*
* Please obtain a copy of the License at
* http://www.opensource.apple.com/apsl/ and read it before using this file.
*
* The Original Code and all software distributed under the License are
* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
* Please see the License for the specific language governing rights and
* limitations under the License.
*
* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
*/
#ifndef _IOKIT_UIODISPATCHQUEUE_H
#define _IOKIT_UIODISPATCHQUEUE_H
#include <DriverKit/OSObject.iig>
#include <DriverKit/OSAction.iig>
#include <DriverKit/IODispatchSource.iig>
typedef int (*IODispatchLogFunction)(const char *format, ...);
typedef void (^IODispatchBlock)(void);
typedef void (*IODispatchFunction)(void * context);
typedef kern_return_t (^IODispatchAction)(void);
typedef void (^IODispatchQueueCancelHandler)(void);
// options for Create()
enum {
kIODispatchQueueReentrant = 0x00000001,
kIODispatchQueueMethodsNotSynchronized = 0x00000002,
};
// options for WakeupWithOptions()
enum {
kIODispatchQueueWakeupAll = 0x00000001,
};
// options for SleepWithDeadline()
enum {
// Sleep on an event which other threads are still waiting on, but has already been signaled
kIODispatchQueueSleepReuseEvent = 0x00000100,
};
/*!
* @class IODispatchQueue
*
* @abstract
* IODispatchQueue provides a queue for ordered execution of blocks.
*
* @discussion
* All blocks submitted to dispatch queues are dequeued in FIFO order.
* By default the queue is serial and will execute one block at a time.
*/
class NATIVE KERNEL IODispatchQueue : public OSObject
{
public:
/*!
* @brief Creates a new dispatch queue object.
* @discussion Creates a new dispatch queue object. All queues are currently serial, executing one block at time
* FIFO order. The new object has retain count 1 and should be released by the caller.
* @param options
kIODispatchQueueReentrant Creates a queue that allows release with the Sleep
method, so that other threads and callers may acquire the queue.
* @param priority No priorities are currently defined, pass zero.
* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
*/
static kern_return_t
Create(
const IODispatchQueueName name,
uint64_t options,
uint64_t priority,
IODispatchQueue ** queue) LOCAL;
virtual bool
init() override;
virtual void
free() override;
/*!
* @brief Determines if the current thread is running on the queue.
* @discussion Determines if the current thread is running on the queue, including if the queue invoked a
* second queue (ie. OnQueue can return true for more than one queue in a given context.)
* @return bool true if current thread is running on this queue.
*/
bool
OnQueue() LOCALONLY;
/*!
* @brief Return the name the queue was created with.
* @discussion Returns a pointer to the queues name. Only valid while the queue is retained.
* @return C-string pointer in the queues internal storage.
*/
const char *
GetName() LOCALONLY;
/*!
* @brief Stop the queue from executing futher work.
* @discussion Stops the queue from dequeuing work, and on completion of any block currently being executed,
* invokes a callback block. Canceling is asynchronous.
* @param handler Block that will executed when the queue has completed any inflight work
* and will not execute further work.
* @return C-string pointer in the queues internal storage.
*/
kern_return_t
Cancel(IODispatchQueueCancelHandler handler) LOCALONLY;
/*!
* @brief Schedule a block to be executed on the queue asynchronously.
* @discussion Schedules work to be done on the queue without waiting for it to complete. The queue will be
* retained until the block completes.
* @param block Block that will executed on the queue, not in the context of the caller.
*/
void
DispatchAsync(IODispatchBlock block) LOCALONLY;
/*!
* @brief C-function callback version of DispatchAsync.
*/
void
DispatchAsync_f(void * context, IODispatchFunction function) LOCALONLY;
/*!
* @brief Schedule a block to be executed concurrently & asynchronously.
* @discussion Schedules work to be done on the queue without waiting for it to complete, and
* concurrently with other blocks executed with DispatchConcurrent. The queue will be
* retained until the block completes. May only be used with a queue created with
* the kIODispatchQueueReentrant option.
* @param block Block that will executed on the queue, not in the context of the caller.
*/
void
DispatchConcurrent(IODispatchBlock block) LOCALONLY;
/*!
* @brief C-function callback version of DispatchConcurrent.
*/
void
DispatchConcurrent_f(void * context, IODispatchFunction function) LOCALONLY;
/*!
* @brief Execute a block on the queue synchronously.
* @discussion Execute a block on the queue synchronously.
* @param block Block that will executed on the queue.
*/
void
DispatchSync(IODispatchBlock block) LOCALONLY;
/*!
* @brief C-function callback version of DispatchSync.
*/
void
DispatchSync_f(void * context, IODispatchFunction function) LOCALONLY;
/*!
* @brief Log the current execution context with respect to any queues the current thread holds.
* @param output printf like output function. The address of IOLog is suitable to be used.
*/
static void
Log(const char * message, IODispatchLogFunction output) LOCALONLY;
/*!
* @brief Version of DispatchSync that returns a kern_return_t status.
*/
kern_return_t
RunAction(IODispatchAction action) LOCALONLY;
/*!
* @brief Put a thread that is currently running the queue to sleep, releasing the queue.
* @discussion Put a thread to sleep waiting for an event but release the queue first.
* In all cases (signal, timeout or error), the caller resumes running on the queue.
* The caller must be currently running on the queue to call Sleep().
* @param event A unique token matching one later passed to Wakeup().
* @param options Pass one of the kIOTimerClock* options to specify the timebase for the
* deadline, or zero for no timeout.
* @param deadline Clock deadline to timeout the sleep.
* @return kIOReturnSuccess or kIOReturnTimeout
*/
kern_return_t
SleepWithDeadline(void * event, uint64_t options, uint64_t deadline) LOCALONLY;
/*!
* @brief Put a thread that is currently running the queue to sleep, releasing the queue.
* @discussion Put a thread to sleep waiting for an event but release the queue first.
* In all cases (signal, timeout or error), the caller resumes running on the queue.
* The caller must be currently running on the queue to call Sleep().
* @param event A unique token matching one later passed to Wakeup().
* @param timeout Clock delay to timeout the sleep.
* @return kIOReturnSuccess or kIOReturnTimeout
*/
kern_return_t
SleepWithTimeout(void * event, uint64_t timeout) LOCALONLY;
/*!
* @brief Synonym for SleepWithTimeout()
*/
kern_return_t
Sleep(void * event, uint64_t timeout) LOCALONLY;
/*!
* @brief Wakes a thread that is blocked in Sleep().
* @discussion Signals a thread that gave up the queue with Sleep() to continue running.
* The caller must be currently running on the queue.
* @param event A unique token matching one passed to Sleep().
* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
*/
kern_return_t
Wakeup(void * event) LOCALONLY;
/*!
* @brief Wakes a thread that is blocked in Sleep().
* @discussion Signals a thread that gave up the queue with Sleep() to continue running.
* The caller must be currently running on the queue.
* @param event A unique token matching one passed to Sleep().
* @param options
kIODispatchQueueWakeupAll wake all threads waiting in Sleep().
The default is to wake only one of any waiting threads.
* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
*/
kern_return_t
WakeupWithOptions(void * event, uint64_t options) LOCALONLY;
};
#if DRIVERKIT_PRIVATE
class EXTENDS (IODispatchQueue) IODispatchQueuePrivate
{
virtual kern_return_t
SetPort(
mach_port_t port PORTMAKESEND);
};
#endif
#endif /* ! _IOKIT_UIODISPATCH_H */