private/workloop_private.h - third_party/swift-corelibs-libdispatch - Git at Google

 /*
  * Copyright (c) 2017-2018 Apple Inc. All rights reserved.
  *
  * @APPLE_APACHE_LICENSE_HEADER_START@
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  *
  * @APPLE_APACHE_LICENSE_HEADER_END@
  */

 /*
  * IMPORTANT: This header file describes INTERNAL interfaces to libdispatch
  * which are subject to change in future releases of Mac OS X. Any applications
  * relying on these interfaces WILL break.
  */

 #ifndef __DISPATCH_WORKLOOP_PRIVATE__
 #define __DISPATCH_WORKLOOP_PRIVATE__

 #ifndef __DISPATCH_INDIRECT__
 #error "Please #include <dispatch/private.h> instead of this file directly."
 #include <dispatch/base.h> // for HeaderDoc
 #endif

 /******************************************************************************\
  *
  * THIS FILE IS AN IN-PROGRESS INTERFACE THAT IS SUBJECT TO CHANGE
  *
 \******************************************************************************/

 DISPATCH_ASSUME_NONNULL_BEGIN

 __BEGIN_DECLS

 /*!
  * @typedef dispatch_workloop_t
  *
  * @abstract
  * Dispatch workloops invoke workitems submitted to them in priority order.
  *
  * @discussion
  * A dispatch workloop is a flavor of dispatch_queue_t that is a priority
  * ordered queue (using the QOS class of the submitted workitems as the
  * ordering).
  *
  * Between each workitem invocation, the workloop will evaluate whether higher
  * priority workitems have since been submitted and execute these first.
  *
  * Serial queues targeting a workloop maintain FIFO execution of their
  * workitems. However, the workloop may reorder workitems submitted to
  * independent serial queues targeting it with respect to each other,
  * based on their priorities.
  *
  * A dispatch workloop is a "subclass" of dispatch_queue_t which can be passed
  * to all APIs accepting a dispatch queue, except for functions from the
  * dispatch_sync() family. dispatch_async_and_wait() must be used for workloop
  * objects. Functions from the dispatch_sync() family on queues targeting
  * a workloop are still permitted but discouraged for performance reasons.
  */
 #if defined(__DISPATCH_BUILDING_DISPATCH__) && !defined(__OBJC__)
 typedef struct dispatch_workloop_s *dispatch_workloop_t;
 #else
 DISPATCH_DECL_SUBCLASS(dispatch_workloop, dispatch_queue);
 #endif

 /*!
  * @function dispatch_workloop_create
  *
  * @abstract
  * Creates a new dispatch workloop to which workitems may be submitted.
  *
  * @param label
  * A string label to attach to the workloop.
  *
  * @result
  * The newly created dispatch workloop.
  */
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 DISPATCH_NOTHROW
 dispatch_workloop_t
 dispatch_workloop_create(const char *_Nullable label);

 /*!
  * @function dispatch_workloop_create_inactive
  *
  * @abstract
  * Creates a new inactive dispatch workloop that can be setup and then
  * activated.
  *
  * @discussion
  * Creating an inactive workloop allows for it to receive further configuration
  * before it is activated, and workitems can be submitted to it.
  *
  * Submitting workitems to an inactive workloop is undefined and will cause the
  * process to be terminated.
  *
  * @param label
  * A string label to attach to the workloop.
  *
  * @result
  * The newly created dispatch workloop.
  */
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 DISPATCH_NOTHROW
 dispatch_workloop_t
 dispatch_workloop_create_inactive(const char *_Nullable label);

 /*!
  * @function dispatch_workloop_set_autorelease_frequency
  *
  * @abstract
  * Sets the autorelease frequency of the workloop.
  *
  * @discussion
  * See dispatch_queue_attr_make_with_autorelease_frequency().
  * The default policy for a workloop is
  * DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM.
  *
  * @param workloop
  * The dispatch workloop to modify.
  *
  * This workloop must be inactive, passing an activated object is undefined
  * and will cause the process to be terminated.
  *
  * @param frequency
  * The requested autorelease frequency.
  */
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 void
 dispatch_workloop_set_autorelease_frequency(dispatch_workloop_t workloop,
 		dispatch_autorelease_frequency_t frequency);

 DISPATCH_ENUM(dispatch_workloop_param_flags, uint64_t,
 	DISPATCH_WORKLOOP_NONE DISPATCH_ENUM_API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) = 0x0,
 	DISPATCH_WORKLOOP_FIXED_PRIORITY DISPATCH_ENUM_API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) = 0x1,
 );

 /*!
  * @function dispatch_workloop_set_qos_class_floor
  *
  * @abstract
  * Sets the QOS class floor of a workloop.
  *
  * @discussion
  * See dispatch_set_qos_class_floor().
  *
  * This function is strictly equivalent to dispatch_set_qos_class_floor() but
  * allows to pass extra flags.
  *
  * Using both dispatch_workloop_set_scheduler_priority() and
  * dispatch_set_qos_class_floor() or dispatch_workloop_set_qos_class_floor()
  * is undefined and will cause the process to be terminated.
  *
  * @param workloop
  * The dispatch workloop to modify.
  *
  * This workloop must be inactive, passing an activated object is undefined
  * and will cause the process to be terminated.
  */
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 void
 dispatch_workloop_set_qos_class_floor(dispatch_workloop_t workloop,
 		dispatch_qos_class_t qos, int relpri, dispatch_workloop_param_flags_t flags);

 /*!
  * @function dispatch_workloop_set_scheduler_priority
  *
  * @abstract
  * Sets the scheduler priority for a dispatch workloop.
  *
  * @discussion
  * This sets the scheduler priority of the threads that the runtime will bring
  * up to service this workloop.
  *
  * QOS propagation still functions on these workloops, but its effect on the
  * priority of the thread brought up to service this workloop is ignored.
  *
  * Using both dispatch_workloop_set_scheduler_priority() and
  * dispatch_set_qos_class_floor() or dispatch_workloop_set_qos_class_floor()
  * is undefined and will cause the process to be terminated.
  *
  * @param workloop
  * The dispatch workloop to modify.
  *
  * This workloop must be inactive, passing an activated object is undefined
  * and will cause the process to be terminated.
  */
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 void
 dispatch_workloop_set_scheduler_priority(dispatch_workloop_t workloop,
 		int priority, dispatch_workloop_param_flags_t flags);

 /*!
  * @function dispatch_workloop_set_cpupercent
  *
  * @abstract
  * Sets the cpu percent and refill attributes for a dispatch workloop.
  *
  * @discussion
  * This should only used if the workloop was also setup with the
  * DISPATCH_WORKLOOP_FIXED_PRIORITY flag as a safe guard against
  * busy loops that could starve the rest of the system forever.
  *
  * If DISPATCH_WORKLOOP_FIXED_PRIORITY wasn't passed, using this function is
  * undefined and will cause the process to be terminated.
  *
  * @param workloop
  * The dispatch workloop to modify.
  *
  * This workloop must be inactive, passing an activated object is undefined
  * and will cause the process to be terminated.
  */
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 void
 dispatch_workloop_set_cpupercent(dispatch_workloop_t workloop, uint8_t percent,
 		uint32_t refillms);

 /*!
  * @function dispatch_workloop_is_current()
  *
  * @abstract
  * Returns whether the current thread has been made by the runtime to service
  * this workloop.
  *
  * @discussion
  * Note that when using <code>dispatch_async_and_wait(workloop, ^{ ... })</code>
  * then <code>workloop</code> will be seen as the "current" one by the submitted
  * workitem, but that is not the case when using dispatch_sync() on a queue
  * targeting the workloop.
  */
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 bool
 dispatch_workloop_is_current(dispatch_workloop_t workloop);

 /*!
  * @function dispatch_workloop_copy_current()
  *
  * @abstract
  * Returns a copy of the workoop that is being serviced on the calling thread
  * if any.
  *
  * @discussion
  * If the thread is not a workqueue thread, or is not servicing a dispatch
  * workloop, then NULL is returned.
  *
  * This returns a retained object that must be released with dispatch_release().
  */
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED DISPATCH_NOTHROW
 dispatch_workloop_t _Nullable
 dispatch_workloop_copy_current(void);

 // Equivalent to dispatch_workloop_set_qos_class_floor(workoop, qos, 0, flags)
 API_DEPRECATED_WITH_REPLACEMENT("dispatch_workloop_set_qos_class_floor",
 		macos(10.14,10.14), ios(12.0,12.0), tvos(12.0,12.0), watchos(5.0,5.0))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 void
 dispatch_workloop_set_qos_class(dispatch_workloop_t workloop,
 		dispatch_qos_class_t qos, dispatch_workloop_param_flags_t flags);

 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_NOTHROW
 bool
 _dispatch_workloop_should_yield_4NW(void);

 /*!
  * @function dispatch_async_and_wait
  *
  * @abstract
  * Submits a block for synchronous execution on a dispatch queue.
  *
  * @discussion
  * Submits a workitem to a dispatch queue like dispatch_async(), however
  * dispatch_async_and_wait() will not return until the workitem has finished.
  *
  * Like functions of the dispatch_sync family, dispatch_async_and_wait() is
  * subject to dead-lock (See dispatch_sync() for details).
  *
  * However, dispatch_async_and_wait() differs from functions of the
  * dispatch_sync family in two fundamental ways: how it respects queue
  * attributes and how it chooses the execution context invoking the workitem.
  *
  * <b>Differences with dispatch_sync()</b>
  *
  * Work items submitted to a queue with dispatch_async_and_wait() observe all
  * queue attributes of that queue when invoked (inluding autorelease frequency
  * or QOS class).
  *
  * When the runtime has brought up a thread to invoke the asynchronous workitems
  * already submitted to the specified queue, that servicing thread will also be
  * used to execute synchronous work submitted to the queue with
  * dispatch_async_and_wait().
  *
  * However, if the runtime has not brought up a thread to service the specified
  * queue (because it has no workitems enqueued, or only synchronous workitems),
  * then dispatch_async_and_wait() will invoke the workitem on the calling thread,
  * similar to the behaviour of functions in the dispatch_sync family.
  *
  * As an exception, if the queue the work is submitted to doesn't target
  * a global concurrent queue (for example because it targets the main queue),
  * then the workitem will never be invoked by the thread calling
  * dispatch_async_and_wait().
  *
  * In other words, dispatch_async_and_wait() is similar to submitting
  * a dispatch_block_create()d workitem to a queue and then waiting on it, as
  * shown in the code example below. However, dispatch_async_and_wait() is
  * significantly more efficient when a new thread is not required to execute
  * the workitem (as it will use the stack of the submitting thread instead of
  * requiring heap allocations).
  *
  * <code>
  *     dispatch_block_t b = dispatch_block_create(0, block);
  *     dispatch_async(queue, b);
  *     dispatch_block_wait(b, DISPATCH_TIME_FOREVER);
  *     Block_release(b);
  * </code>
  *
  * @param queue
  * The target dispatch queue to which the block is submitted.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param block
  * The block to be invoked on the target dispatch queue.
  * The result of passing NULL in this parameter is undefined.
  */
 #ifdef __BLOCKS__
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 void
 dispatch_async_and_wait(dispatch_queue_t queue,
 		DISPATCH_NOESCAPE dispatch_block_t block);
 #endif

 /*!
  * @function dispatch_async_and_wait_f
  *
  * @abstract
  * Submits a function for synchronous execution on a dispatch queue.
  *
  * @discussion
  * See dispatch_async_and_wait() for details.
  *
  * @param queue
  * The target dispatch queue to which the function is submitted.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param context
  * The application-defined context parameter to pass to the function.
  *
  * @param work
  * The application-defined function to invoke on the target queue. The first
  * parameter passed to this function is the context provided to
  * dispatch_async_and_wait_f().
  * The result of passing NULL in this parameter is undefined.
  */
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 void
 dispatch_async_and_wait_f(dispatch_queue_t queue,
 		void *_Nullable context, dispatch_function_t work);

 /*!
  * @function dispatch_barrier_async_and_wait
  *
  * @abstract
  * Submits a block for synchronous execution on a dispatch queue.
  *
  * @discussion
  * Submits a block to a dispatch queue like dispatch_async_and_wait(), but marks
  * that block as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT
  * queues).
  *
  * @param queue
  * The target dispatch queue to which the block is submitted.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param work
  * The application-defined block to invoke on the target queue.
  * The result of passing NULL in this parameter is undefined.
  */
 #ifdef __BLOCKS__
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 void
 dispatch_barrier_async_and_wait(dispatch_queue_t queue,
 		DISPATCH_NOESCAPE dispatch_block_t block);
 #endif

 /*!
  * @function dispatch_barrier_async_and_wait_f
  *
  * @abstract
  * Submits a function for synchronous execution on a dispatch queue.
  *
  * @discussion
  * Submits a function to a dispatch queue like dispatch_async_and_wait_f(), but
  * marks that function as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT
  * queues).
  *
  * @param queue
  * The target dispatch queue to which the function is submitted.
  * The result of passing NULL in this parameter is undefined.
  *
  * @param context
  * The application-defined context parameter to pass to the function.
  *
  * @param work
  * The application-defined function to invoke on the target queue. The first
  * parameter passed to this function is the context provided to
  * dispatch_barrier_async_and_wait_f().
  * The result of passing NULL in this parameter is undefined.
  */
 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 void
 dispatch_barrier_async_and_wait_f(dispatch_queue_t queue,
 		void *_Nullable context, dispatch_function_t work);

 __END_DECLS

 DISPATCH_ASSUME_NONNULL_END

 #endif
	/*
	* Copyright (c) 2017-2018 Apple Inc. All rights reserved.
	*
	* @APPLE_APACHE_LICENSE_HEADER_START@
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*
	* @APPLE_APACHE_LICENSE_HEADER_END@
	*/

	/*
	* IMPORTANT: This header file describes INTERNAL interfaces to libdispatch
	* which are subject to change in future releases of Mac OS X. Any applications
	* relying on these interfaces WILL break.
	*/

	#ifndef __DISPATCH_WORKLOOP_PRIVATE__
	#define __DISPATCH_WORKLOOP_PRIVATE__

	#ifndef __DISPATCH_INDIRECT__
	#error "Please #include <dispatch/private.h> instead of this file directly."
	#include <dispatch/base.h> // for HeaderDoc
	#endif

	/******************************************************************************\
	*
	* THIS FILE IS AN IN-PROGRESS INTERFACE THAT IS SUBJECT TO CHANGE
	*
	\******************************************************************************/

	DISPATCH_ASSUME_NONNULL_BEGIN

	__BEGIN_DECLS

	/*!
	* @typedef dispatch_workloop_t
	*
	* @abstract
	* Dispatch workloops invoke workitems submitted to them in priority order.
	*
	* @discussion
	* A dispatch workloop is a flavor of dispatch_queue_t that is a priority
	* ordered queue (using the QOS class of the submitted workitems as the
	* ordering).
	*
	* Between each workitem invocation, the workloop will evaluate whether higher
	* priority workitems have since been submitted and execute these first.
	*
	* Serial queues targeting a workloop maintain FIFO execution of their
	* workitems. However, the workloop may reorder workitems submitted to
	* independent serial queues targeting it with respect to each other,
	* based on their priorities.
	*
	* A dispatch workloop is a "subclass" of dispatch_queue_t which can be passed
	* to all APIs accepting a dispatch queue, except for functions from the
	* dispatch_sync() family. dispatch_async_and_wait() must be used for workloop
	* objects. Functions from the dispatch_sync() family on queues targeting
	* a workloop are still permitted but discouraged for performance reasons.
	*/
	#if defined(__DISPATCH_BUILDING_DISPATCH__) && !defined(__OBJC__)
	typedef struct dispatch_workloop_s *dispatch_workloop_t;
	#else
	DISPATCH_DECL_SUBCLASS(dispatch_workloop, dispatch_queue);
	#endif

	/*!
	* @function dispatch_workloop_create
	*
	* @abstract
	* Creates a new dispatch workloop to which workitems may be submitted.
	*
	* @param label
	* A string label to attach to the workloop.
	*
	* @result
	* The newly created dispatch workloop.
	*/
	API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
	DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
	DISPATCH_NOTHROW
	dispatch_workloop_t
	dispatch_workloop_create(const char *_Nullable label);

	/*!
	* @function dispatch_workloop_create_inactive
	*
	* @abstract
	* Creates a new inactive dispatch workloop that can be setup and then
	* activated.
	*
	* @discussion
	* Creating an inactive workloop allows for it to receive further configuration
	* before it is activated, and workitems can be submitted to it.
	*
	* Submitting workitems to an inactive workloop is undefined and will cause the
	* process to be terminated.
	*
	* @param label
	* A string label to attach to the workloop.
	*
	* @result
	* The newly created dispatch workloop.
	*/
	API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
	DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
	DISPATCH_NOTHROW
	dispatch_workloop_t
	dispatch_workloop_create_inactive(const char *_Nullable label);

	/*!
	* @function dispatch_workloop_set_autorelease_frequency
	*
	* @abstract
	* Sets the autorelease frequency of the workloop.
	*
	* @discussion
	* See dispatch_queue_attr_make_with_autorelease_frequency().
	* The default policy for a workloop is
	* DISPATCH_AUTORELEASE_FREQUENCY_WORK_ITEM.
	*
	* @param workloop
	* The dispatch workloop to modify.
	*
	* This workloop must be inactive, passing an activated object is undefined
	* and will cause the process to be terminated.
	*
	* @param frequency
	* The requested autorelease frequency.
	*/
	API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
	void
	dispatch_workloop_set_autorelease_frequency(dispatch_workloop_t workloop,
	dispatch_autorelease_frequency_t frequency);

	DISPATCH_ENUM(dispatch_workloop_param_flags, uint64_t,
	DISPATCH_WORKLOOP_NONE DISPATCH_ENUM_API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) = 0x0,
	DISPATCH_WORKLOOP_FIXED_PRIORITY DISPATCH_ENUM_API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) = 0x1,
	);

	/*!
	* @function dispatch_workloop_set_qos_class_floor
	*
	* @abstract
	* Sets the QOS class floor of a workloop.
	*
	* @discussion
	* See dispatch_set_qos_class_floor().
	*
	* This function is strictly equivalent to dispatch_set_qos_class_floor() but
	* allows to pass extra flags.
	*
	* Using both dispatch_workloop_set_scheduler_priority() and
	* dispatch_set_qos_class_floor() or dispatch_workloop_set_qos_class_floor()
	* is undefined and will cause the process to be terminated.
	*
	* @param workloop
	* The dispatch workloop to modify.
	*
	* This workloop must be inactive, passing an activated object is undefined
	* and will cause the process to be terminated.
	*/
	API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
	void
	dispatch_workloop_set_qos_class_floor(dispatch_workloop_t workloop,
	dispatch_qos_class_t qos, int relpri, dispatch_workloop_param_flags_t flags);

	/*!
	* @function dispatch_workloop_set_scheduler_priority
	*
	* @abstract
	* Sets the scheduler priority for a dispatch workloop.
	*
	* @discussion
	* This sets the scheduler priority of the threads that the runtime will bring
	* up to service this workloop.
	*
	* QOS propagation still functions on these workloops, but its effect on the
	* priority of the thread brought up to service this workloop is ignored.
	*
	* Using both dispatch_workloop_set_scheduler_priority() and
	* dispatch_set_qos_class_floor() or dispatch_workloop_set_qos_class_floor()
	* is undefined and will cause the process to be terminated.
	*
	* @param workloop
	* The dispatch workloop to modify.
	*
	* This workloop must be inactive, passing an activated object is undefined
	* and will cause the process to be terminated.
	*/
	API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
	void
	dispatch_workloop_set_scheduler_priority(dispatch_workloop_t workloop,
	int priority, dispatch_workloop_param_flags_t flags);

	/*!
	* @function dispatch_workloop_set_cpupercent
	*
	* @abstract
	* Sets the cpu percent and refill attributes for a dispatch workloop.
	*
	* @discussion
	* This should only used if the workloop was also setup with the
	* DISPATCH_WORKLOOP_FIXED_PRIORITY flag as a safe guard against
	* busy loops that could starve the rest of the system forever.
	*
	* If DISPATCH_WORKLOOP_FIXED_PRIORITY wasn't passed, using this function is
	* undefined and will cause the process to be terminated.
	*
	* @param workloop
	* The dispatch workloop to modify.
	*
	* This workloop must be inactive, passing an activated object is undefined
	* and will cause the process to be terminated.
	*/
	API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
	void
	dispatch_workloop_set_cpupercent(dispatch_workloop_t workloop, uint8_t percent,
	uint32_t refillms);

	/*!
	* @function dispatch_workloop_is_current()
	*
	* @abstract
	* Returns whether the current thread has been made by the runtime to service
	* this workloop.
	*
	* @discussion
	* Note that when using <code>dispatch_async_and_wait(workloop, ^{ ... })</code>
	* then <code>workloop</code> will be seen as the "current" one by the submitted
	* workitem, but that is not the case when using dispatch_sync() on a queue
	* targeting the workloop.
	*/
	API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
	bool
	dispatch_workloop_is_current(dispatch_workloop_t workloop);

	/*!
	* @function dispatch_workloop_copy_current()
	*
	* @abstract
	* Returns a copy of the workoop that is being serviced on the calling thread
	* if any.
	*
	* @discussion
	* If the thread is not a workqueue thread, or is not servicing a dispatch
	* workloop, then NULL is returned.
	*
	* This returns a retained object that must be released with dispatch_release().
	*/
	API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
	DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED DISPATCH_NOTHROW
	dispatch_workloop_t _Nullable
	dispatch_workloop_copy_current(void);

	// Equivalent to dispatch_workloop_set_qos_class_floor(workoop, qos, 0, flags)
	API_DEPRECATED_WITH_REPLACEMENT("dispatch_workloop_set_qos_class_floor",
	macos(10.14,10.14), ios(12.0,12.0), tvos(12.0,12.0), watchos(5.0,5.0))
	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
	void
	dispatch_workloop_set_qos_class(dispatch_workloop_t workloop,
	dispatch_qos_class_t qos, dispatch_workloop_param_flags_t flags);

	API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
	DISPATCH_EXPORT DISPATCH_NOTHROW
	bool
	_dispatch_workloop_should_yield_4NW(void);

	/*!
	* @function dispatch_async_and_wait
	*
	* @abstract
	* Submits a block for synchronous execution on a dispatch queue.
	*
	* @discussion
	* Submits a workitem to a dispatch queue like dispatch_async(), however
	* dispatch_async_and_wait() will not return until the workitem has finished.
	*
	* Like functions of the dispatch_sync family, dispatch_async_and_wait() is
	* subject to dead-lock (See dispatch_sync() for details).
	*
	* However, dispatch_async_and_wait() differs from functions of the
	* dispatch_sync family in two fundamental ways: how it respects queue
	* attributes and how it chooses the execution context invoking the workitem.
	*
	* <b>Differences with dispatch_sync()</b>
	*
	* Work items submitted to a queue with dispatch_async_and_wait() observe all
	* queue attributes of that queue when invoked (inluding autorelease frequency
	* or QOS class).
	*
	* When the runtime has brought up a thread to invoke the asynchronous workitems
	* already submitted to the specified queue, that servicing thread will also be
	* used to execute synchronous work submitted to the queue with
	* dispatch_async_and_wait().
	*
	* However, if the runtime has not brought up a thread to service the specified
	* queue (because it has no workitems enqueued, or only synchronous workitems),
	* then dispatch_async_and_wait() will invoke the workitem on the calling thread,
	* similar to the behaviour of functions in the dispatch_sync family.
	*
	* As an exception, if the queue the work is submitted to doesn't target
	* a global concurrent queue (for example because it targets the main queue),
	* then the workitem will never be invoked by the thread calling
	* dispatch_async_and_wait().
	*
	* In other words, dispatch_async_and_wait() is similar to submitting
	* a dispatch_block_create()d workitem to a queue and then waiting on it, as
	* shown in the code example below. However, dispatch_async_and_wait() is
	* significantly more efficient when a new thread is not required to execute
	* the workitem (as it will use the stack of the submitting thread instead of
	* requiring heap allocations).
	*
	* <code>
	* dispatch_block_t b = dispatch_block_create(0, block);
	* dispatch_async(queue, b);
	* dispatch_block_wait(b, DISPATCH_TIME_FOREVER);
	* Block_release(b);
	* </code>
	*
	* @param queue
	* The target dispatch queue to which the block is submitted.
	* The result of passing NULL in this parameter is undefined.
	*
	* @param block
	* The block to be invoked on the target dispatch queue.
	* The result of passing NULL in this parameter is undefined.
	*/
	#ifdef __BLOCKS__
	API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
	void
	dispatch_async_and_wait(dispatch_queue_t queue,
	DISPATCH_NOESCAPE dispatch_block_t block);
	#endif

	/*!
	* @function dispatch_async_and_wait_f
	*
	* @abstract
	* Submits a function for synchronous execution on a dispatch queue.
	*
	* @discussion
	* See dispatch_async_and_wait() for details.
	*
	* @param queue
	* The target dispatch queue to which the function is submitted.
	* The result of passing NULL in this parameter is undefined.
	*
	* @param context
	* The application-defined context parameter to pass to the function.
	*
	* @param work
	* The application-defined function to invoke on the target queue. The first
	* parameter passed to this function is the context provided to
	* dispatch_async_and_wait_f().
	* The result of passing NULL in this parameter is undefined.
	*/
	API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
	DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
	void
	dispatch_async_and_wait_f(dispatch_queue_t queue,
	void *_Nullable context, dispatch_function_t work);

	/*!
	* @function dispatch_barrier_async_and_wait
	*
	* @abstract
	* Submits a block for synchronous execution on a dispatch queue.
	*
	* @discussion
	* Submits a block to a dispatch queue like dispatch_async_and_wait(), but marks
	* that block as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT
	* queues).
	*
	* @param queue
	* The target dispatch queue to which the block is submitted.
	* The result of passing NULL in this parameter is undefined.
	*
	* @param work
	* The application-defined block to invoke on the target queue.
	* The result of passing NULL in this parameter is undefined.
	*/
	#ifdef __BLOCKS__
	API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
	void
	dispatch_barrier_async_and_wait(dispatch_queue_t queue,
	DISPATCH_NOESCAPE dispatch_block_t block);
	#endif

	/*!
	* @function dispatch_barrier_async_and_wait_f
	*
	* @abstract
	* Submits a function for synchronous execution on a dispatch queue.
	*
	* @discussion
	* Submits a function to a dispatch queue like dispatch_async_and_wait_f(), but
	* marks that function as a barrier (relevant only on DISPATCH_QUEUE_CONCURRENT
	* queues).
	*
	* @param queue
	* The target dispatch queue to which the function is submitted.
	* The result of passing NULL in this parameter is undefined.
	*
	* @param context
	* The application-defined context parameter to pass to the function.
	*
	* @param work
	* The application-defined function to invoke on the target queue. The first
	* parameter passed to this function is the context provided to
	* dispatch_barrier_async_and_wait_f().
	* The result of passing NULL in this parameter is undefined.
	*/
	API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
	DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
	void
	dispatch_barrier_async_and_wait_f(dispatch_queue_t queue,
	void *_Nullable context, dispatch_function_t work);

	__END_DECLS

	DISPATCH_ASSUME_NONNULL_END

	#endif