/*
 * 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 */