[apple/libdispatch.git] / private / source_private.h

/*
 * Copyright (c) 2008-2013 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_SOURCE_PRIVATE__
#define __DISPATCH_SOURCE_PRIVATE__

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

DISPATCH_ASSUME_NONNULL_BEGIN

__BEGIN_DECLS

/*!
 * @const DISPATCH_SOURCE_TYPE_TIMER_WITH_AGGREGATE
 * @discussion A dispatch timer source that is part of a timer aggregate.
 * The handle is the dispatch timer aggregate object.
 * The mask specifies which flags from dispatch_source_timer_flags_t to apply.
 */
#define DISPATCH_SOURCE_TYPE_TIMER_WITH_AGGREGATE \
		(&_dispatch_source_type_timer_with_aggregate)
__OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
DISPATCH_SOURCE_TYPE_DECL(timer_with_aggregate);

/*!
 * @const DISPATCH_SOURCE_TYPE_INTERVAL
 * @discussion A dispatch source that submits the event handler block at a
 * specified time interval, phase-aligned with all other interval sources on
 * the system that have the same interval value.
 *
 * The initial submission of the event handler will occur at some point during
 * the first time interval after the source is created (assuming the source is
 * resumed at that time).
 *
 * By default, the unit for the interval value is milliseconds and the leeway
 * (maximum amount of time any individual handler submission may be deferred to
 * align with other system activity) for the source is fixed at interval/2.
 *
 * If the DISPATCH_INTERVAL_UI_ANIMATION flag is specified, the unit for the
 * interval value is animation frames (1/60th of a second) and the leeway is
 * fixed at one frame.
 *
 * The handle is the interval value in milliseconds or frames.
 * The mask specifies which flags from dispatch_source_timer_flags_t to apply.
 */
#define DISPATCH_SOURCE_TYPE_INTERVAL (&_dispatch_source_type_interval)
__OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
DISPATCH_SOURCE_TYPE_DECL(interval);

/*!
 * @const DISPATCH_SOURCE_TYPE_VFS
 * @discussion Apple-internal dispatch source that monitors for vfs events
 * defined by dispatch_vfs_flags_t.
 * The handle is a process identifier (pid_t).
 */
#define DISPATCH_SOURCE_TYPE_VFS (&_dispatch_source_type_vfs)
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) DISPATCH_LINUX_UNAVAILABLE()
DISPATCH_EXPORT const struct dispatch_source_type_s _dispatch_source_type_vfs;

/*!
 * @const DISPATCH_SOURCE_TYPE_VM
 * @discussion A dispatch source that monitors virtual memory
 * The mask is a mask of desired events from dispatch_source_vm_flags_t.
 * This type is deprecated, use DISPATCH_SOURCE_TYPE_MEMORYPRESSURE instead.
 */
#define DISPATCH_SOURCE_TYPE_VM (&_dispatch_source_type_vm)
__OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_7, __MAC_10_10, __IPHONE_4_3,
		__IPHONE_8_0, "Use DISPATCH_SOURCE_TYPE_MEMORYPRESSURE instead")
DISPATCH_LINUX_UNAVAILABLE()
DISPATCH_EXPORT const struct dispatch_source_type_s _dispatch_source_type_vm;

/*!
 * @const DISPATCH_SOURCE_TYPE_MEMORYSTATUS
 * @discussion A dispatch source that monitors memory status
 * The mask is a mask of desired events from
 * dispatch_source_memorystatus_flags_t.
 */
#define DISPATCH_SOURCE_TYPE_MEMORYSTATUS (&_dispatch_source_type_memorystatus)
__OSX_DEPRECATED(10.9, 10.12, "Use DISPATCH_SOURCE_TYPE_MEMORYPRESSURE instead")
__IOS_DEPRECATED(6.0, 10.0, "Use DISPATCH_SOURCE_TYPE_MEMORYPRESSURE instead")
__TVOS_DEPRECATED(6.0, 10.0, "Use DISPATCH_SOURCE_TYPE_MEMORYPRESSURE instead")
__WATCHOS_DEPRECATED(1.0, 3.0, "Use DISPATCH_SOURCE_TYPE_MEMORYPRESSURE instead")
DISPATCH_LINUX_UNAVAILABLE()
DISPATCH_EXPORT const struct dispatch_source_type_s
		_dispatch_source_type_memorystatus;

/*!
 * @const DISPATCH_SOURCE_TYPE_SOCK
 * @discussion A dispatch source that monitors events on socket state changes.
 */
#define DISPATCH_SOURCE_TYPE_SOCK (&_dispatch_source_type_sock)
__OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0) DISPATCH_LINUX_UNAVAILABLE()
DISPATCH_EXPORT const struct dispatch_source_type_s _dispatch_source_type_sock;

__END_DECLS

/*!
 * @enum dispatch_source_sock_flags_t
 *
 * @constant DISPATCH_SOCK_CONNRESET
 * Received RST
 *
 * @constant DISPATCH_SOCK_READCLOSED
 * Read side is shutdown
 *
 * @constant DISPATCH_SOCK_WRITECLOSED
 * Write side is shutdown
 *
 * @constant DISPATCH_SOCK_TIMEOUT
 * Timeout: rexmt, keep-alive or persist
 *
 * @constant DISPATCH_SOCK_NOSRCADDR
 * Source address not available
 *
 * @constant DISPATCH_SOCK_IFDENIED
 * Interface denied connection
 *
 * @constant DISPATCH_SOCK_SUSPEND
 * Output queue suspended
 *
 * @constant DISPATCH_SOCK_RESUME
 * Output queue resumed
 *
 * @constant DISPATCH_SOCK_KEEPALIVE
 * TCP Keepalive received
 *
 * @constant DISPATCH_SOCK_CONNECTED
 * Socket is connected
 *
 * @constant DISPATCH_SOCK_DISCONNECTED
 * Socket is disconnected
 *
 * @constant DISPATCH_SOCK_CONNINFO_UPDATED
 * Connection info was updated
 *
 * @constant DISPATCH_SOCK_NOTIFY_ACK
 * Notify acknowledgement
 */
enum {
	DISPATCH_SOCK_CONNRESET = 0x00000001,
	DISPATCH_SOCK_READCLOSED = 0x00000002,
	DISPATCH_SOCK_WRITECLOSED = 0x00000004,
	DISPATCH_SOCK_TIMEOUT = 0x00000008,
	DISPATCH_SOCK_NOSRCADDR = 0x00000010,
	DISPATCH_SOCK_IFDENIED = 0x00000020,
	DISPATCH_SOCK_SUSPEND = 0x00000040,
	DISPATCH_SOCK_RESUME = 0x00000080,
	DISPATCH_SOCK_KEEPALIVE = 0x00000100,
	DISPATCH_SOCK_ADAPTIVE_WTIMO = 0x00000200,
	DISPATCH_SOCK_ADAPTIVE_RTIMO = 0x00000400,
	DISPATCH_SOCK_CONNECTED = 0x00000800,
	DISPATCH_SOCK_DISCONNECTED = 0x00001000,
	DISPATCH_SOCK_CONNINFO_UPDATED = 0x00002000,
	DISPATCH_SOCK_NOTIFY_ACK = 0x00004000,
};

/*!
 * @enum dispatch_source_vfs_flags_t
 *
 * @constant DISPATCH_VFS_NOTRESP
 * Server down.
 *
 * @constant DISPATCH_VFS_NEEDAUTH
 * Server bad auth.
 *
 * @constant DISPATCH_VFS_LOWDISK
 * We're low on space.
 *
 * @constant DISPATCH_VFS_MOUNT
 * New filesystem arrived.
 *
 * @constant DISPATCH_VFS_UNMOUNT
 * Filesystem has left.
 *
 * @constant DISPATCH_VFS_DEAD
 * Filesystem is dead, needs force unmount.
 *
 * @constant DISPATCH_VFS_ASSIST
 * Filesystem needs assistance from external program.
 *
 * @constant DISPATCH_VFS_NOTRESPLOCK
 * Server lockd down.
 *
 * @constant DISPATCH_VFS_UPDATE
 * Filesystem information has changed.
 *
 * @constant DISPATCH_VFS_VERYLOWDISK
 * File system has *very* little disk space left.
 *
 * @constant DISPATCH_VFS_QUOTA
 * We hit a user quota (quotactl) for this filesystem.
 */
enum {
	DISPATCH_VFS_NOTRESP = 0x0001,
	DISPATCH_VFS_NEEDAUTH = 0x0002,
	DISPATCH_VFS_LOWDISK = 0x0004,
	DISPATCH_VFS_MOUNT = 0x0008,
	DISPATCH_VFS_UNMOUNT = 0x0010,
	DISPATCH_VFS_DEAD = 0x0020,
	DISPATCH_VFS_ASSIST = 0x0040,
	DISPATCH_VFS_NOTRESPLOCK = 0x0080,
	DISPATCH_VFS_UPDATE = 0x0100,
	DISPATCH_VFS_VERYLOWDISK = 0x0200,
	DISPATCH_VFS_QUOTA = 0x1000,
};

/*!
 * @enum dispatch_source_timer_flags_t
 *
 * @constant DISPATCH_TIMER_BACKGROUND
 * Specifies that the timer is used to trigger low priority maintenance-level
 * activity and that the system may apply larger minimum leeway values to the
 * timer in order to align it with other system activity.
 *
 * @constant DISPATCH_INTERVAL_UI_ANIMATION
 * Specifies that the interval source is used for UI animation. The unit for
 * the interval value of such sources is frames (1/60th of a second) and the
 * leeway is fixed at one frame.
 */
enum {
	DISPATCH_TIMER_BACKGROUND = 0x2,
	DISPATCH_INTERVAL_UI_ANIMATION = 0x20,
};

/*!
 * @enum dispatch_source_mach_send_flags_t
 *
 * @constant DISPATCH_MACH_SEND_POSSIBLE
 * The mach port corresponding to the given send right has space available
 * for messages. Delivered only once a mach_msg() to that send right with
 * options MACH_SEND_MSG|MACH_SEND_TIMEOUT|MACH_SEND_NOTIFY has returned
 * MACH_SEND_TIMED_OUT (and not again until the next such mach_msg() timeout).
 * NOTE: The source must have registered the send right for monitoring with the
 *       system for such a mach_msg() to arm the send-possible notifcation, so
 *       the initial send attempt must occur from a source registration handler.
 */
enum {
	DISPATCH_MACH_SEND_POSSIBLE = 0x8,
};

/*!
 * @enum dispatch_source_proc_flags_t
 *
 * @constant DISPATCH_PROC_REAP
 * The process has been reaped by the parent process via wait*().
 * This flag is deprecated and will be removed in a future release.
 */
enum {
	DISPATCH_PROC_REAP __OSX_AVAILABLE_BUT_DEPRECATED(
			__MAC_10_6, __MAC_10_9, __IPHONE_4_0, __IPHONE_7_0) = 0x10000000,
};

/*!
 * @enum dispatch_source_vm_flags_t
 *
 * @constant DISPATCH_VM_PRESSURE
 * The VM has experienced memory pressure.
 */

enum {
	DISPATCH_VM_PRESSURE __OSX_AVAILABLE_BUT_DEPRECATED_MSG(
			__MAC_10_7, __MAC_10_10, __IPHONE_4_3, __IPHONE_8_0,
			"Use DISPATCH_MEMORYPRESSURE_WARN instead") = 0x80000000,
};

/*!
 * @typedef dispatch_source_memorypressure_flags_t
 * Type of dispatch_source_memorypressure flags
 *
 * @constant DISPATCH_MEMORYPRESSURE_LOW_SWAP
 * The system's memory pressure state has entered the "low swap" condition.
 * Restricted to the root user.
 */
enum {
	DISPATCH_MEMORYPRESSURE_LOW_SWAP
			__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0) = 0x08,
};

/*!
 * @enum dispatch_source_memorystatus_flags_t
 * @warning Deprecated, see DISPATCH_MEMORYPRESSURE_*
 */
enum {
	DISPATCH_MEMORYSTATUS_PRESSURE_NORMAL
			__OSX_DEPRECATED(10.9, 10.12, "Use DISPATCH_MEMORYPRESSURE_NORMAL instead")
			__IOS_DEPRECATED(6.0, 10.0, "Use DISPATCH_MEMORYPRESSURE_NORMAL instead")
			__TVOS_DEPRECATED(6.0, 10.0, "Use DISPATCH_MEMORYPRESSURE_NORMAL instead")
			__WATCHOS_DEPRECATED(1.0, 3.0, "Use DISPATCH_MEMORYPRESSURE_NORMAL instead")
			= 0x01,
	DISPATCH_MEMORYSTATUS_PRESSURE_WARN
			__OSX_DEPRECATED(10.9, 10.12, "Use DISPATCH_MEMORYPRESSURE_WARN instead")
			__IOS_DEPRECATED(6.0, 10.0, "Use DISPATCH_MEMORYPRESSURE_WARN instead")
			__TVOS_DEPRECATED(6.0, 10.0, "Use DISPATCH_MEMORYPRESSURE_WARN instead")
			__WATCHOS_DEPRECATED(1.0, 3.0, "Use DISPATCH_MEMORYPRESSURE_WARN instead")
			= 0x02,
	DISPATCH_MEMORYSTATUS_PRESSURE_CRITICAL
			__OSX_DEPRECATED(10.9, 10.12, "Use DISPATCH_MEMORYPRESSURE_CRITICAL instead")
			__IOS_DEPRECATED(8.0, 10.0, "Use DISPATCH_MEMORYPRESSURE_CRITICAL instead")
			__TVOS_DEPRECATED(8.0, 10.0, "Use DISPATCH_MEMORYPRESSURE_CRITICAL instead")
			__WATCHOS_DEPRECATED(1.0, 3.0, "Use DISPATCH_MEMORYPRESSURE_CRITICAL instead")
			= 0x04,
	DISPATCH_MEMORYSTATUS_LOW_SWAP
			__OSX_DEPRECATED(10.10, 10.12, "Use DISPATCH_MEMORYPRESSURE_LOW_SWAP instead")
			__IOS_DEPRECATED(8.0, 10.0, "Use DISPATCH_MEMORYPRESSURE_LOW_SWAP instead")
			__TVOS_DEPRECATED(8.0, 10.0, "Use DISPATCH_MEMORYPRESSURE_LOW_SWAP instead")
			__WATCHOS_DEPRECATED(1.0, 3.0, "Use DISPATCH_MEMORYPRESSURE_LOW_SWAP instead")
			= 0x08,
};

/*!
 * @typedef dispatch_source_memorypressure_flags_t
 * Type of dispatch_source_memorypressure flags
 *
 * @constant DISPATCH_MEMORYPRESSURE_PROC_LIMIT_WARN
 * The memory of the process has crossed 80% of its high watermark limit.
 *
 * @constant DISPATCH_MEMORYPRESSURE_PROC_LIMIT_CRITICAL
 * The memory of the process has reached 100% of its high watermark limit.
 */
enum {
	DISPATCH_MEMORYPRESSURE_PROC_LIMIT_WARN
			__OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.10)
			__TVOS_AVAILABLE(10.10) __WATCHOS_AVAILABLE(3.0) = 0x10,

	DISPATCH_MEMORYPRESSURE_PROC_LIMIT_CRITICAL
		__OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.10)
		__TVOS_AVAILABLE(10.10) __WATCHOS_AVAILABLE(3.0) = 0x20,
};


__BEGIN_DECLS

/*!
 * @function dispatch_source_cancel_and_wait
 *
 * @abstract
 * Synchronously cancel the dispatch source, preventing any further invocation
 * of its event handler block.
 *
 * @discussion
 * Cancellation prevents any further invocation of handler blocks for the
 * specified dispatch source, but does not interrupt a handler block that is
 * already in progress.
 *
 * When this function returns, any handler block that may have been in progress
 * has returned, the specified source has been unregistered and it is safe to
 * reclaim any system resource (such as file descriptors or mach ports) that
 * the specified source was monitoring.
 *
 * If the specified dispatch source is inactive, it will be activated as a side
 * effect of calling this function.
 *
 * It is possible to call this function from several threads concurrently,
 * and it is the responsibility of the callers to synchronize reclaiming the
 * associated system resources.
 *
 * This function is not subject to priority inversion when it is waiting on
 * a handler block still in progress, unlike patterns based on waiting on
 * a dispatch semaphore or a dispatch group signaled (or left) from the source
 * cancel handler.
 *
 * This function must not be called if the specified source has a cancel
 * handler set, or from the context of its handler blocks.
 *
 * This function must not be called from the context of the target queue of
 * the specified source or from any queue that synchronizes with it. Note that
 * calling dispatch_source_cancel() from such a context already guarantees
 * that no handler is in progress, and that no new event will be delivered.
 *
 * This function must not be called on sources suspended with an explicit
 * call to dispatch_suspend(), or being concurrently activated on another
 * thread.
 *
 * @param source
 * The dispatch source to be canceled.
 * The result of passing NULL in this parameter is undefined.
 */
__OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.10)
__TVOS_AVAILABLE(10.10) __WATCHOS_AVAILABLE(3.0)
DISPATCH_EXPORT DISPATCH_NOTHROW
void
dispatch_source_cancel_and_wait(dispatch_source_t source);

/*!
 * @typedef dispatch_timer_aggregate_t
 *
 * @abstract
 * Dispatch timer aggregates are sets of related timers.
 */
DISPATCH_DECL(dispatch_timer_aggregate);

/*!
 * @function dispatch_timer_aggregate_create
 *
 * @abstract
 * Creates a new dispatch timer aggregate.
 *
 * @discussion
 * A dispatch timer aggregate is a set of related timers whose overall timing
 * parameters can be queried.
 *
 * Timers are added to an aggregate when a timer source is created with type
 * DISPATCH_SOURCE_TYPE_TIMER_WITH_AGGREGATE.
 *
 * @result
 * The newly created dispatch timer aggregate.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
DISPATCH_NOTHROW
dispatch_timer_aggregate_t
dispatch_timer_aggregate_create(void);

/*!
 * @function dispatch_timer_aggregate_get_delay
 *
 * @abstract
 * Retrieves the delay until a timer in the given aggregate will next fire.
 *
 * @param aggregate
 * The dispatch timer aggregate to query.
 *
 * @param leeway_ptr
 * Optional pointer to a variable filled with the leeway (in ns) that will be
 * applied to the return value. May be NULL.
 *
 * @result
 * Delay in ns from now.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
DISPATCH_EXPORT DISPATCH_NOTHROW
uint64_t
dispatch_timer_aggregate_get_delay(dispatch_timer_aggregate_t aggregate,
		uint64_t *_Nullable leeway_ptr);

#if __has_include(<mach/mach.h>)
/*!
 * @typedef dispatch_mig_callback_t
 *
 * @abstract
 * The signature of a function that handles Mach message delivery and response.
 */
typedef boolean_t (*dispatch_mig_callback_t)(mach_msg_header_t *message,
		mach_msg_header_t *reply);

__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) DISPATCH_LINUX_UNAVAILABLE()
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
mach_msg_return_t
dispatch_mig_server(dispatch_source_t ds, size_t maxmsgsz,
		dispatch_mig_callback_t callback);

/*!
 * @function dispatch_mach_msg_get_context
 *
 * @abstract
 * Extract the context pointer from a mach message trailer.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) DISPATCH_LINUX_UNAVAILABLE()
DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NONNULL_ALL
DISPATCH_NOTHROW
void *_Nullable
dispatch_mach_msg_get_context(mach_msg_header_t *msg);
#endif

__END_DECLS

DISPATCH_ASSUME_NONNULL_END

#endif
Commit	Line	Data
0ab74447	1	/*
517da941	2	* Copyright (c) 2008-2013 Apple Inc. All rights reserved.
0ab74447 A	3	*
0ab74447 A	4	* @APPLE_APACHE_LICENSE_HEADER_START@
e85f4437	5	*
0ab74447 A	6	* Licensed under the Apache License, Version 2.0 (the "License");
	7	* you may not use this file except in compliance with the License.
	8	* You may obtain a copy of the License at
e85f4437	9	*
0ab74447	10	* http://www.apache.org/licenses/LICENSE-2.0
e85f4437	11	*
0ab74447 A	12	* Unless required by applicable law or agreed to in writing, software
	13	* distributed under the License is distributed on an "AS IS" BASIS,
	14	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	15	* See the License for the specific language governing permissions and
	16	* limitations under the License.
e85f4437	17	*
0ab74447 A	18	* @APPLE_APACHE_LICENSE_HEADER_END@
	19	*/
	20
	21	/*
	22	* IMPORTANT: This header file describes INTERNAL interfaces to libdispatch
	23	* which are subject to change in future releases of Mac OS X. Any applications
	24	* relying on these interfaces WILL break.
	25	*/
	26
	27	#ifndef __DISPATCH_SOURCE_PRIVATE__
	28	#define __DISPATCH_SOURCE_PRIVATE__
	29
	30	#ifndef __DISPATCH_INDIRECT__
c093abd6	31	#error "Please #include <dispatch/private.h> instead of this file directly."
0ab74447 A	32	#include <dispatch/base.h> // for HeaderDoc
	33	#endif
	34
beb15981 A	35	DISPATCH_ASSUME_NONNULL_BEGIN
beb15981 A	36
45201a42 A	37	__BEGIN_DECLS
45201a42 A	38
517da941 A	39	/*!
	40	* @const DISPATCH_SOURCE_TYPE_TIMER_WITH_AGGREGATE
	41	* @discussion A dispatch timer source that is part of a timer aggregate.
	42	* The handle is the dispatch timer aggregate object.
	43	* The mask specifies which flags from dispatch_source_timer_flags_t to apply.
	44	*/
	45	#define DISPATCH_SOURCE_TYPE_TIMER_WITH_AGGREGATE \
	46	(&_dispatch_source_type_timer_with_aggregate)
	47	__OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
	48	DISPATCH_SOURCE_TYPE_DECL(timer_with_aggregate);
	49
	50	/*!
	51	* @const DISPATCH_SOURCE_TYPE_INTERVAL
	52	* @discussion A dispatch source that submits the event handler block at a
	53	* specified time interval, phase-aligned with all other interval sources on
	54	* the system that have the same interval value.
	55	*
	56	* The initial submission of the event handler will occur at some point during
	57	* the first time interval after the source is created (assuming the source is
	58	* resumed at that time).
	59	*
	60	* By default, the unit for the interval value is milliseconds and the leeway
	61	* (maximum amount of time any individual handler submission may be deferred to
	62	* align with other system activity) for the source is fixed at interval/2.
	63	*
	64	* If the DISPATCH_INTERVAL_UI_ANIMATION flag is specified, the unit for the
	65	* interval value is animation frames (1/60th of a second) and the leeway is
	66	* fixed at one frame.
	67	*
	68	* The handle is the interval value in milliseconds or frames.
	69	* The mask specifies which flags from dispatch_source_timer_flags_t to apply.
	70	*/
	71	#define DISPATCH_SOURCE_TYPE_INTERVAL (&_dispatch_source_type_interval)
	72	__OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
	73	DISPATCH_SOURCE_TYPE_DECL(interval);
	74
0ab74447 A	75	/*!
	76	* @const DISPATCH_SOURCE_TYPE_VFS
	77	* @discussion Apple-internal dispatch source that monitors for vfs events
	78	* defined by dispatch_vfs_flags_t.
	79	* The handle is a process identifier (pid_t).
	80	*/
	81	#define DISPATCH_SOURCE_TYPE_VFS (&_dispatch_source_type_vfs)
beb15981	82	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) DISPATCH_LINUX_UNAVAILABLE()
e85f4437 A	83	DISPATCH_EXPORT const struct dispatch_source_type_s _dispatch_source_type_vfs;
	84
	85	/*!
	86	* @const DISPATCH_SOURCE_TYPE_VM
	87	* @discussion A dispatch source that monitors virtual memory
	88	* The mask is a mask of desired events from dispatch_source_vm_flags_t.
beb15981	89	* This type is deprecated, use DISPATCH_SOURCE_TYPE_MEMORYPRESSURE instead.
e85f4437 A	90	*/
e85f4437 A	91	#define DISPATCH_SOURCE_TYPE_VM (&_dispatch_source_type_vm)
98cf8cd2	92	__OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_7, __MAC_10_10, __IPHONE_4_3,
beb15981 A	93	__IPHONE_8_0, "Use DISPATCH_SOURCE_TYPE_MEMORYPRESSURE instead")
beb15981 A	94	DISPATCH_LINUX_UNAVAILABLE()
e85f4437	95	DISPATCH_EXPORT const struct dispatch_source_type_s _dispatch_source_type_vm;
0ab74447	96
517da941 A	97	/*!
	98	* @const DISPATCH_SOURCE_TYPE_MEMORYSTATUS
	99	* @discussion A dispatch source that monitors memory status
	100	* The mask is a mask of desired events from
	101	* dispatch_source_memorystatus_flags_t.
	102	*/
	103	#define DISPATCH_SOURCE_TYPE_MEMORYSTATUS (&_dispatch_source_type_memorystatus)
beb15981 A	104	__OSX_DEPRECATED(10.9, 10.12, "Use DISPATCH_SOURCE_TYPE_MEMORYPRESSURE instead")
	105	__IOS_DEPRECATED(6.0, 10.0, "Use DISPATCH_SOURCE_TYPE_MEMORYPRESSURE instead")
	106	__TVOS_DEPRECATED(6.0, 10.0, "Use DISPATCH_SOURCE_TYPE_MEMORYPRESSURE instead")
	107	__WATCHOS_DEPRECATED(1.0, 3.0, "Use DISPATCH_SOURCE_TYPE_MEMORYPRESSURE instead")
	108	DISPATCH_LINUX_UNAVAILABLE()
517da941 A	109	DISPATCH_EXPORT const struct dispatch_source_type_s
	110	_dispatch_source_type_memorystatus;
	111
c093abd6 A	112	/*!
	113	* @const DISPATCH_SOURCE_TYPE_SOCK
	114	* @discussion A dispatch source that monitors events on socket state changes.
	115	*/
	116	#define DISPATCH_SOURCE_TYPE_SOCK (&_dispatch_source_type_sock)
beb15981	117	__OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0) DISPATCH_LINUX_UNAVAILABLE()
c093abd6 A	118	DISPATCH_EXPORT const struct dispatch_source_type_s _dispatch_source_type_sock;
c093abd6 A	119
45201a42 A	120	__END_DECLS
45201a42 A	121
c093abd6 A	122	/*!
	123	* @enum dispatch_source_sock_flags_t
	124	*
	125	* @constant DISPATCH_SOCK_CONNRESET
	126	* Received RST
	127	*
	128	* @constant DISPATCH_SOCK_READCLOSED
	129	* Read side is shutdown
	130	*
	131	* @constant DISPATCH_SOCK_WRITECLOSED
	132	* Write side is shutdown
	133	*
	134	* @constant DISPATCH_SOCK_TIMEOUT
	135	* Timeout: rexmt, keep-alive or persist
	136	*
	137	* @constant DISPATCH_SOCK_NOSRCADDR
	138	* Source address not available
	139	*
	140	* @constant DISPATCH_SOCK_IFDENIED
	141	* Interface denied connection
	142	*
	143	* @constant DISPATCH_SOCK_SUSPEND
	144	* Output queue suspended
	145	*
	146	* @constant DISPATCH_SOCK_RESUME
	147	* Output queue resumed
	148	*
	149	* @constant DISPATCH_SOCK_KEEPALIVE
	150	* TCP Keepalive received
	151	*
517da941 A	152	* @constant DISPATCH_SOCK_CONNECTED
	153	* Socket is connected
	154	*
	155	* @constant DISPATCH_SOCK_DISCONNECTED
	156	* Socket is disconnected
	157	*
	158	* @constant DISPATCH_SOCK_CONNINFO_UPDATED
	159	* Connection info was updated
beb15981 A	160	*
	161	* @constant DISPATCH_SOCK_NOTIFY_ACK
	162	* Notify acknowledgement
c093abd6 A	163	*/
	164	enum {
	165	DISPATCH_SOCK_CONNRESET = 0x00000001,
	166	DISPATCH_SOCK_READCLOSED = 0x00000002,
	167	DISPATCH_SOCK_WRITECLOSED = 0x00000004,
	168	DISPATCH_SOCK_TIMEOUT = 0x00000008,
	169	DISPATCH_SOCK_NOSRCADDR = 0x00000010,
	170	DISPATCH_SOCK_IFDENIED = 0x00000020,
	171	DISPATCH_SOCK_SUSPEND = 0x00000040,
	172	DISPATCH_SOCK_RESUME = 0x00000080,
	173	DISPATCH_SOCK_KEEPALIVE = 0x00000100,
517da941 A	174	DISPATCH_SOCK_ADAPTIVE_WTIMO = 0x00000200,
	175	DISPATCH_SOCK_ADAPTIVE_RTIMO = 0x00000400,
	176	DISPATCH_SOCK_CONNECTED = 0x00000800,
	177	DISPATCH_SOCK_DISCONNECTED = 0x00001000,
	178	DISPATCH_SOCK_CONNINFO_UPDATED = 0x00002000,
beb15981	179	DISPATCH_SOCK_NOTIFY_ACK = 0x00004000,
c093abd6 A	180	};
c093abd6 A	181
0ab74447 A	182	/*!
	183	* @enum dispatch_source_vfs_flags_t
	184	*
	185	* @constant DISPATCH_VFS_NOTRESP
	186	* Server down.
	187	*
	188	* @constant DISPATCH_VFS_NEEDAUTH
	189	* Server bad auth.
	190	*
	191	* @constant DISPATCH_VFS_LOWDISK
	192	* We're low on space.
	193	*
	194	* @constant DISPATCH_VFS_MOUNT
	195	* New filesystem arrived.
	196	*
	197	* @constant DISPATCH_VFS_UNMOUNT
	198	* Filesystem has left.
	199	*
	200	* @constant DISPATCH_VFS_DEAD
	201	* Filesystem is dead, needs force unmount.
	202	*
	203	* @constant DISPATCH_VFS_ASSIST
	204	* Filesystem needs assistance from external program.
	205	*
	206	* @constant DISPATCH_VFS_NOTRESPLOCK
	207	* Server lockd down.
	208	*
	209	* @constant DISPATCH_VFS_UPDATE
	210	* Filesystem information has changed.
	211	*
	212	* @constant DISPATCH_VFS_VERYLOWDISK
	213	* File system has very little disk space left.
7a22f034 A	214	*
	215	* @constant DISPATCH_VFS_QUOTA
	216	* We hit a user quota (quotactl) for this filesystem.
0ab74447 A	217	*/
	218	enum {
	219	DISPATCH_VFS_NOTRESP = 0x0001,
	220	DISPATCH_VFS_NEEDAUTH = 0x0002,
	221	DISPATCH_VFS_LOWDISK = 0x0004,
	222	DISPATCH_VFS_MOUNT = 0x0008,
	223	DISPATCH_VFS_UNMOUNT = 0x0010,
	224	DISPATCH_VFS_DEAD = 0x0020,
	225	DISPATCH_VFS_ASSIST = 0x0040,
	226	DISPATCH_VFS_NOTRESPLOCK = 0x0080,
	227	DISPATCH_VFS_UPDATE = 0x0100,
	228	DISPATCH_VFS_VERYLOWDISK = 0x0200,
7a22f034	229	DISPATCH_VFS_QUOTA = 0x1000,
0ab74447 A	230	};
0ab74447 A	231
517da941 A	232	/*!
	233	* @enum dispatch_source_timer_flags_t
	234	*
	235	* @constant DISPATCH_TIMER_BACKGROUND
	236	* Specifies that the timer is used to trigger low priority maintenance-level
	237	* activity and that the system may apply larger minimum leeway values to the
	238	* timer in order to align it with other system activity.
	239	*
	240	* @constant DISPATCH_INTERVAL_UI_ANIMATION
	241	* Specifies that the interval source is used for UI animation. The unit for
	242	* the interval value of such sources is frames (1/60th of a second) and the
	243	* leeway is fixed at one frame.
	244	*/
	245	enum {
	246	DISPATCH_TIMER_BACKGROUND = 0x2,
	247	DISPATCH_INTERVAL_UI_ANIMATION = 0x20,
	248	};
	249
0ab74447 A	250	/*!
	251	* @enum dispatch_source_mach_send_flags_t
	252	*
e85f4437 A	253	* @constant DISPATCH_MACH_SEND_POSSIBLE
	254	* The mach port corresponding to the given send right has space available
	255	* for messages. Delivered only once a mach_msg() to that send right with
	256	* options MACH_SEND_MSG\|MACH_SEND_TIMEOUT\|MACH_SEND_NOTIFY has returned
	257	* MACH_SEND_TIMED_OUT (and not again until the next such mach_msg() timeout).
	258	* NOTE: The source must have registered the send right for monitoring with the
	259	* system for such a mach_msg() to arm the send-possible notifcation, so
	260	* the initial send attempt must occur from a source registration handler.
0ab74447 A	261	*/
0ab74447 A	262	enum {
e85f4437	263	DISPATCH_MACH_SEND_POSSIBLE = 0x8,
0ab74447 A	264	};
	265
	266	/*!
	267	* @enum dispatch_source_proc_flags_t
	268	*
	269	* @constant DISPATCH_PROC_REAP
517da941 A	270	* The process has been reaped by the parent process via wait*().
517da941 A	271	* This flag is deprecated and will be removed in a future release.
0ab74447 A	272	*/
0ab74447 A	273	enum {
517da941 A	274	DISPATCH_PROC_REAP __OSX_AVAILABLE_BUT_DEPRECATED(
517da941 A	275	__MAC_10_6, __MAC_10_9, __IPHONE_4_0, __IPHONE_7_0) = 0x10000000,
0ab74447 A	276	};
0ab74447 A	277
e85f4437 A	278	/*!
	279	* @enum dispatch_source_vm_flags_t
	280	*
	281	* @constant DISPATCH_VM_PRESSURE
	282	* The VM has experienced memory pressure.
	283	*/
	284
	285	enum {
98cf8cd2 A	286	DISPATCH_VM_PRESSURE __OSX_AVAILABLE_BUT_DEPRECATED_MSG(
98cf8cd2 A	287	__MAC_10_7, __MAC_10_10, __IPHONE_4_3, __IPHONE_8_0,
beb15981	288	"Use DISPATCH_MEMORYPRESSURE_WARN instead") = 0x80000000,
e85f4437 A	289	};
e85f4437 A	290
517da941	291	/*!
beb15981 A	292	* @typedef dispatch_source_memorypressure_flags_t
beb15981 A	293	* Type of dispatch_source_memorypressure flags
517da941	294	*
beb15981	295	* @constant DISPATCH_MEMORYPRESSURE_LOW_SWAP
98cf8cd2 A	296	* The system's memory pressure state has entered the "low swap" condition.
98cf8cd2 A	297	* Restricted to the root user.
517da941	298	*/
beb15981 A	299	enum {
	300	DISPATCH_MEMORYPRESSURE_LOW_SWAP
	301	__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0) = 0x08,
	302	};
517da941	303
beb15981 A	304	/*!
	305	* @enum dispatch_source_memorystatus_flags_t
	306	* @warning Deprecated, see DISPATCH_MEMORYPRESSURE_*
	307	*/
517da941	308	enum {
98cf8cd2	309	DISPATCH_MEMORYSTATUS_PRESSURE_NORMAL
beb15981 A	310	__OSX_DEPRECATED(10.9, 10.12, "Use DISPATCH_MEMORYPRESSURE_NORMAL instead")
	311	__IOS_DEPRECATED(6.0, 10.0, "Use DISPATCH_MEMORYPRESSURE_NORMAL instead")
	312	__TVOS_DEPRECATED(6.0, 10.0, "Use DISPATCH_MEMORYPRESSURE_NORMAL instead")
	313	__WATCHOS_DEPRECATED(1.0, 3.0, "Use DISPATCH_MEMORYPRESSURE_NORMAL instead")
	314	= 0x01,
98cf8cd2	315	DISPATCH_MEMORYSTATUS_PRESSURE_WARN
beb15981 A	316	__OSX_DEPRECATED(10.9, 10.12, "Use DISPATCH_MEMORYPRESSURE_WARN instead")
	317	__IOS_DEPRECATED(6.0, 10.0, "Use DISPATCH_MEMORYPRESSURE_WARN instead")
	318	__TVOS_DEPRECATED(6.0, 10.0, "Use DISPATCH_MEMORYPRESSURE_WARN instead")
	319	__WATCHOS_DEPRECATED(1.0, 3.0, "Use DISPATCH_MEMORYPRESSURE_WARN instead")
	320	= 0x02,
98cf8cd2	321	DISPATCH_MEMORYSTATUS_PRESSURE_CRITICAL
beb15981 A	322	__OSX_DEPRECATED(10.9, 10.12, "Use DISPATCH_MEMORYPRESSURE_CRITICAL instead")
	323	__IOS_DEPRECATED(8.0, 10.0, "Use DISPATCH_MEMORYPRESSURE_CRITICAL instead")
	324	__TVOS_DEPRECATED(8.0, 10.0, "Use DISPATCH_MEMORYPRESSURE_CRITICAL instead")
	325	__WATCHOS_DEPRECATED(1.0, 3.0, "Use DISPATCH_MEMORYPRESSURE_CRITICAL instead")
	326	= 0x04,
98cf8cd2	327	DISPATCH_MEMORYSTATUS_LOW_SWAP
beb15981 A	328	__OSX_DEPRECATED(10.10, 10.12, "Use DISPATCH_MEMORYPRESSURE_LOW_SWAP instead")
	329	__IOS_DEPRECATED(8.0, 10.0, "Use DISPATCH_MEMORYPRESSURE_LOW_SWAP instead")
	330	__TVOS_DEPRECATED(8.0, 10.0, "Use DISPATCH_MEMORYPRESSURE_LOW_SWAP instead")
	331	__WATCHOS_DEPRECATED(1.0, 3.0, "Use DISPATCH_MEMORYPRESSURE_LOW_SWAP instead")
	332	= 0x08,
	333	};
	334
	335	/*!
	336	* @typedef dispatch_source_memorypressure_flags_t
	337	* Type of dispatch_source_memorypressure flags
	338	*
	339	* @constant DISPATCH_MEMORYPRESSURE_PROC_LIMIT_WARN
	340	* The memory of the process has crossed 80% of its high watermark limit.
	341	*
	342	* @constant DISPATCH_MEMORYPRESSURE_PROC_LIMIT_CRITICAL
	343	* The memory of the process has reached 100% of its high watermark limit.
	344	*/
	345	enum {
	346	DISPATCH_MEMORYPRESSURE_PROC_LIMIT_WARN
	347	__OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.10)
	348	__TVOS_AVAILABLE(10.10) __WATCHOS_AVAILABLE(3.0) = 0x10,
	349
	350	DISPATCH_MEMORYPRESSURE_PROC_LIMIT_CRITICAL
	351	__OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.10)
	352	__TVOS_AVAILABLE(10.10) __WATCHOS_AVAILABLE(3.0) = 0x20,
517da941 A	353	};
517da941 A	354
beb15981	355
0ab74447 A	356	__BEGIN_DECLS
0ab74447 A	357
beb15981 A	358	/*!
	359	* @function dispatch_source_cancel_and_wait
	360	*
	361	* @abstract
	362	* Synchronously cancel the dispatch source, preventing any further invocation
	363	* of its event handler block.
	364	*
	365	* @discussion
	366	* Cancellation prevents any further invocation of handler blocks for the
	367	* specified dispatch source, but does not interrupt a handler block that is
	368	* already in progress.
	369	*
	370	* When this function returns, any handler block that may have been in progress
	371	* has returned, the specified source has been unregistered and it is safe to
	372	* reclaim any system resource (such as file descriptors or mach ports) that
	373	* the specified source was monitoring.
	374	*
	375	* If the specified dispatch source is inactive, it will be activated as a side
	376	* effect of calling this function.
	377	*
	378	* It is possible to call this function from several threads concurrently,
	379	* and it is the responsibility of the callers to synchronize reclaiming the
	380	* associated system resources.
	381	*
	382	* This function is not subject to priority inversion when it is waiting on
	383	* a handler block still in progress, unlike patterns based on waiting on
	384	* a dispatch semaphore or a dispatch group signaled (or left) from the source
	385	* cancel handler.
	386	*
	387	* This function must not be called if the specified source has a cancel
	388	* handler set, or from the context of its handler blocks.
	389	*
	390	* This function must not be called from the context of the target queue of
	391	* the specified source or from any queue that synchronizes with it. Note that
	392	* calling dispatch_source_cancel() from such a context already guarantees
	393	* that no handler is in progress, and that no new event will be delivered.
	394	*
	395	* This function must not be called on sources suspended with an explicit
	396	* call to dispatch_suspend(), or being concurrently activated on another
	397	* thread.
	398	*
	399	* @param source
	400	* The dispatch source to be canceled.
	401	* The result of passing NULL in this parameter is undefined.
	402	*/
	403	__OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.10)
	404	__TVOS_AVAILABLE(10.10) __WATCHOS_AVAILABLE(3.0)
	405	DISPATCH_EXPORT DISPATCH_NOTHROW
	406	void
	407	dispatch_source_cancel_and_wait(dispatch_source_t source);
	408
517da941 A	409	/*!
	410	* @typedef dispatch_timer_aggregate_t
	411	*
	412	* @abstract
	413	* Dispatch timer aggregates are sets of related timers.
	414	*/
	415	DISPATCH_DECL(dispatch_timer_aggregate);
	416
	417	/*!
	418	* @function dispatch_timer_aggregate_create
	419	*
	420	* @abstract
	421	* Creates a new dispatch timer aggregate.
	422	*
	423	* @discussion
	424	* A dispatch timer aggregate is a set of related timers whose overall timing
	425	* parameters can be queried.
	426	*
	427	* Timers are added to an aggregate when a timer source is created with type
	428	* DISPATCH_SOURCE_TYPE_TIMER_WITH_AGGREGATE.
	429	*
	430	* @result
	431	* The newly created dispatch timer aggregate.
	432	*/
	433	__OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
	434	DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
	435	DISPATCH_NOTHROW
	436	dispatch_timer_aggregate_t
	437	dispatch_timer_aggregate_create(void);
	438
	439	/*!
	440	* @function dispatch_timer_aggregate_get_delay
	441	*
	442	* @abstract
	443	* Retrieves the delay until a timer in the given aggregate will next fire.
	444	*
	445	* @param aggregate
	446	* The dispatch timer aggregate to query.
	447	*
	448	* @param leeway_ptr
	449	* Optional pointer to a variable filled with the leeway (in ns) that will be
	450	* applied to the return value. May be NULL.
	451	*
	452	* @result
	453	* Delay in ns from now.
	454	*/
	455	__OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
	456	DISPATCH_EXPORT DISPATCH_NOTHROW
	457	uint64_t
	458	dispatch_timer_aggregate_get_delay(dispatch_timer_aggregate_t aggregate,
beb15981	459	uint64_t *_Nullable leeway_ptr);
517da941	460
beb15981	461	#if __has_include(<mach/mach.h>)
0ab74447 A	462	/*!
	463	* @typedef dispatch_mig_callback_t
	464	*
	465	* @abstract
	466	* The signature of a function that handles Mach message delivery and response.
	467	*/
e85f4437 A	468	typedef boolean_t (dispatch_mig_callback_t)(mach_msg_header_t message,
e85f4437 A	469	mach_msg_header_t *reply);
0ab74447	470
beb15981	471	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) DISPATCH_LINUX_UNAVAILABLE()
e85f4437	472	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
0ab74447	473	mach_msg_return_t
e85f4437 A	474	dispatch_mig_server(dispatch_source_t ds, size_t maxmsgsz,
e85f4437 A	475	dispatch_mig_callback_t callback);
517da941 A	476
	477	/*!
	478	* @function dispatch_mach_msg_get_context
	479	*
	480	* @abstract
	481	* Extract the context pointer from a mach message trailer.
	482	*/
beb15981	483	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) DISPATCH_LINUX_UNAVAILABLE()
517da941 A	484	DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NONNULL_ALL
517da941 A	485	DISPATCH_NOTHROW
beb15981	486	void *_Nullable
517da941	487	dispatch_mach_msg_get_context(mach_msg_header_t *msg);
e85f4437	488	#endif
0ab74447 A	489
	490	__END_DECLS
	491
beb15981 A	492	DISPATCH_ASSUME_NONNULL_END
beb15981 A	493
0ab74447	494	#endif