iokit/DriverKit/IODispatchQueue.iig

   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
  36 typedef int (*IODispatchLogFunction)(const char *format, ...);
  37 typedef void (^IODispatchBlock)(void);
  38 typedef void (*IODispatchFunction)(void * context);
  39 typedef void (^IODispatchQueueCancelHandler)(void);
  40
  41
  42 /*!
  43  * @class IODispatchQueue
  44  *
  45  * @abstract
  46  * IODispatchQueue provides a queue for ordered execution of blocks.
  47  *
  48  * @discussion
  49  * All blocks submitted to dispatch queues are dequeued in FIFO order.
  50  * By default the queue is serial and will execute one block at a time.
  51  */
  52
  53 class NATIVE KERNEL IODispatchQueue : public OSObject
  54 {
  55 public:
  56     /*!
  57      * @brief       Creates a new dispatch queue object.
  58      * @discussion  Creates a new dispatch queue object. All queues are currently serial, executing one block at time
  59      *              FIFO order. The new object has retain count 1 and should be released by the caller.
  60      * @param       options No options are currently defined, pass zero.
  61      * @param       priority No priorities are currently defined, pass zero.
  62      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
  63      */
  64         static kern_return_t
  65         Create(
  66                 const IODispatchQueueName name,
  67                 uint64_t                  options,
  68                 uint64_t                  priority,
  69                 IODispatchQueue        ** queue) LOCAL;
  70
  71         virtual bool
  72         init() override;
  73
  74         virtual void
  75         free() override;
  76
  77     /*!
  78      * @brief       Determines if the current thread is running on the queue.
  79      * @discussion  Determines if the current thread is running on the queue, including if the queue invoked a
  80      *              second queue (ie. OnQueue can return true for more than one queue in a given context.)
  81      * @return      bool true if current thread is running on this queue.
  82      */
  83         bool
  84         OnQueue() LOCALONLY;
  85
  86     /*!
  87      * @brief       Return the name the queue was created with.
  88      * @discussion  Returns a pointer to the queues name. Only valid while the queue is retained.
  89      * @return      C-string pointer in the queues internal storage.
  90      */
  91         const char *
  92         GetName() LOCALONLY;
  93
  94     /*!
  95      * @brief       Stop the queue from executing futher work.
  96      * @discussion  Stops the queue from dequeuing work, and on completion of any block currently being executed,
  97      *              invokes a callback block. Canceling is asynchronous.
  98      * @param       handler Block that will executed when the queue has completed any inflight work
  99      *              and will not execute further work.
 100      * @return      C-string pointer in the queues internal storage.
 101      */
 102         kern_return_t
 103         Cancel(IODispatchQueueCancelHandler handler) LOCALONLY;
 104
 105     /*!
 106      * @brief       Schedule a block to be executed on the queue asynchronously.
 107      * @discussion  Schedules work to be done on the queue without waiting for it to complete. The queue will be
 108      *              retained until the block completes.
 109      * @param       block Block that will executed on the queue, not in the context of the caller.
 110      */
 111         void
 112         DispatchAsync(IODispatchBlock block) LOCALONLY;
 113
 114     /*!
 115      * @brief       C-function callback version of DispatchAsync.
 116          */
 117         void
 118         DispatchAsync_f(void * context, IODispatchFunction function) LOCALONLY;
 119
 120         void
 121         DispatchSync(IODispatchBlock block) LOCALONLY;
 122
 123     /*!
 124      * @brief       C-function callback version of DispatchSync.
 125          */
 126         void
 127         DispatchSync_f(void * context, IODispatchFunction function) LOCALONLY;
 128
 129     /*!
 130      * @brief       Log the current execution context with respect to any queues the current thread holds.
 131      * @param       output printf like output function. The address of IOLog is suitable to be used.
 132          */
 133         static void
 134         Log(const char * message, IODispatchLogFunction output) LOCALONLY;
 135 };
 136
 137 #if DRIVERKIT_PRIVATE
 138 class EXTENDS (IODispatchQueue) IODispatchQueuePrivate
 139 {
 140         virtual kern_return_t
 141         SetPort(
 142                 mach_port_t port PORTMAKESEND);
 143 };
 144 #endif
 145
 146 #endif /* ! _IOKIT_UIODISPATCH_H */