private/mach_private.h

/*
 * Copyright (c) 2012-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_MACH_PRIVATE__
#define __DISPATCH_MACH_PRIVATE__

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

__BEGIN_DECLS

#if DISPATCH_MACH_SPI

#define DISPATCH_MACH_SPI_VERSION 20161026

#include <mach/mach.h>

DISPATCH_ASSUME_NONNULL_BEGIN

/*!
 * @functiongroup Dispatch Mach Channel SPI
 *
 * IMPORTANT: This is Libsystem-internal SPI not intended for general use and
 * is subject to change at any time without warning.
 */

/*!
 * @typedef dispatch_mach_t
 * A dispatch mach channel asynchronously recevives and sends mach messages.
 */
DISPATCH_DECL(dispatch_mach);

/*!
 * @typedef dispatch_mach_reason_t
 * Reasons for a mach channel handler to be invoked, or the result of an
 * immediate send attempt.
 *
 * @const DISPATCH_MACH_CONNECTED
 * The channel has been connected. The first handler invocation on a channel
 * after calling dispatch_mach_connect() will have this reason.
 *
 * @const DISPATCH_MACH_MESSAGE_RECEIVED
 * A message was received, it is passed in the message parameter.
 *
 * @const DISPATCH_MACH_MESSAGE_SENT
 * A message was sent, it is passed in the message parameter (so that associated
 * resources can be disposed of).
 *
 * @const DISPATCH_MACH_MESSAGE_SEND_FAILED
 * A message failed to be sent, it is passed in the message parameter (so that
 * associated resources can be disposed of), along with the error code from
 * mach_msg().
 *
 * @const DISPATCH_MACH_MESSAGE_NOT_SENT
 * A message was not sent due to the channel being canceled or reconnected, it
 * is passed in the message parameter (so that associated resources can be
 * disposed of).
 *
 * @const DISPATCH_MACH_BARRIER_COMPLETED
 * A barrier block has finished executing.
 *
 * @const DISPATCH_MACH_DISCONNECTED
 * The channel has been disconnected by a call to dispatch_mach_reconnect() or
 * dispatch_mach_cancel(), an empty message is passed in the message parameter
 * (so that associated port rights can be disposed of).
 * The message header will contain either a remote port with a previously
 * connected send right, or a local port with a previously connected receive
 * right (if the channel was canceled), or a local port with a receive right
 * that was being monitored for a direct reply to a message previously sent to
 * the channel (if no reply was received).
 *
 * @const DISPATCH_MACH_CANCELED
 * The channel has been canceled.
 *
 * @const DISPATCH_MACH_REPLY_RECEIVED
 * A synchronous reply to a call to dispatch_mach_send_and_wait_for_reply() has
 * been received on another thread, an empty message is passed in the message
 * parameter (so that associated port rights can be disposed of).
 * The message header will contain a local port with a receive right associated
 * with the reply to the message that was synchronously sent to the channel.
 *
 * @const DISPATCH_MACH_NEEDS_DEFERRED_SEND
 * The message could not be sent synchronously. Only returned from a send with
 * result operation and never passed to a channel handler. Indicates that the
 * message passed to the send operation must not be disposed of until it is
 * returned via the channel handler.
 *
 * @const DISPATCH_MACH_SIGTERM_RECEIVED
 * A SIGTERM signal has been received. This notification is delivered at most
 * once during the lifetime of the channel. This event is sent only for XPC
 * channels (i.e. channels that were created by calling
 * dispatch_mach_create_4libxpc()) and only if the
 * dmxh_enable_sigterm_notification function in the XPC hooks structure is not
 * set or it returned true when it was called at channel activation time.
 *
 * @const DISPATCH_MACH_ASYNC_WAITER_DISCONNECTED
 * The channel has been disconnected by a call to dispatch_mach_reconnect() or
 * dispatch_mach_cancel(), an empty message is passed in the message parameter
 * (so that associated port rights can be disposed of). The message header will
 * contain a local port with the receive right previously allocated to receive
 * an asynchronous reply to a message previously sent to the channel. Used 
 * only if the channel is disconnected while waiting for a reply to a message
 * sent with dispatch_mach_send_with_result_and_async_reply_4libxpc().
 */
DISPATCH_ENUM(dispatch_mach_reason, unsigned long,
	DISPATCH_MACH_CONNECTED = 1,
	DISPATCH_MACH_MESSAGE_RECEIVED,
	DISPATCH_MACH_MESSAGE_SENT,
	DISPATCH_MACH_MESSAGE_SEND_FAILED,
	DISPATCH_MACH_MESSAGE_NOT_SENT,
	DISPATCH_MACH_BARRIER_COMPLETED,
	DISPATCH_MACH_DISCONNECTED,
	DISPATCH_MACH_CANCELED,
	DISPATCH_MACH_REPLY_RECEIVED,
	DISPATCH_MACH_NEEDS_DEFERRED_SEND,
	DISPATCH_MACH_SIGTERM_RECEIVED,
	DISPATCH_MACH_ASYNC_WAITER_DISCONNECTED,
	DISPATCH_MACH_REASON_LAST, /* unused */
);

/*!
 * @typedef dispatch_mach_send_flags_t
 * Flags that can be passed to the *with_flags send functions.
 */
DISPATCH_ENUM(dispatch_mach_send_flags, unsigned long,
	DISPATCH_MACH_SEND_DEFAULT = 0,
);

/*!
 * @typedef dispatch_mach_trailer_t
 * Trailer type of mach message received by dispatch mach channels
 */

typedef mach_msg_context_trailer_t dispatch_mach_trailer_t;

/*!
 * @constant DISPATCH_MACH_RECEIVE_MAX_INLINE_MESSAGE_SIZE
 * Maximum size of a message that can be received inline by a dispatch mach
 * channel, reception of larger messages requires an extra roundtrip through
 * the kernel.
 */

#define DISPATCH_MACH_RECEIVE_MAX_INLINE_MESSAGE_SIZE \
		(0x4000 - sizeof(dispatch_mach_trailer_t))

/*!
 * @typedef dispatch_mach_msg_t
 * A dispatch mach message encapsulates messages received or sent with dispatch
 * mach channels.
 */
DISPATCH_DECL(dispatch_mach_msg);

/*!
 * @typedef dispatch_mach_msg_destructor_t
 * Dispatch mach message object destructors.
 *
 * @const DISPATCH_MACH_MSG_DESTRUCTOR_DEFAULT
 * Message buffer storage is internal to the object, if a buffer is supplied
 * during object creation, its contents are copied.
 *
 * @const DISPATCH_MACH_MSG_DESTRUCTOR_FREE
 * Message buffer will be deallocated with free(3).
 *
 * @const DISPATCH_MACH_MSG_DESTRUCTOR_FREE
 * Message buffer will be deallocated with vm_deallocate.
 */
DISPATCH_ENUM(dispatch_mach_msg_destructor, unsigned int,
	DISPATCH_MACH_MSG_DESTRUCTOR_DEFAULT = 0,
	DISPATCH_MACH_MSG_DESTRUCTOR_FREE,
	DISPATCH_MACH_MSG_DESTRUCTOR_VM_DEALLOCATE,
);

/*!
 * @function dispatch_mach_msg_create
 * Creates a dispatch mach message object, either with a newly allocated message
 * buffer of given size, or from an existing message buffer that will be
 * deallocated with the specified destructor when the object is released.
 *
 * If a non-NULL reference to a pointer is provided in 'msg_ptr', it is filled
 * with the location of the (possibly newly allocated) message buffer.
 *
 * It is the responsibility of the application to ensure that it does not modify
 * the underlying message buffer once the dispatch mach message object is passed
 * to other dispatch mach API.
 *
 * @param msg			The message buffer to create the message object from.
 *						If 'destructor' is DISPATCH_MACH_MSG_DESTRUCTOR_DEFAULT,
 *						this argument may be NULL to leave the newly allocated
 *						message buffer zero-initialized.
 * @param size			The size of the message buffer.
 *						Must be >= sizeof(mach_msg_header_t)
 * @param destructor	The destructor to use to deallocate the message buffer
 *						when the object is released.
 * @param msg_ptr		A pointer to a pointer variable to be filled with the
 *						location of the (possibly newly allocated) message
 *						buffer, or NULL.
 * @result				A newly created dispatch mach message object.
 */
API_AVAILABLE(macos(10.9), ios(7.0))
DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
DISPATCH_NOTHROW
dispatch_mach_msg_t
dispatch_mach_msg_create(mach_msg_header_t *_Nullable msg, size_t size,
		dispatch_mach_msg_destructor_t destructor,
		mach_msg_header_t *_Nonnull *_Nullable msg_ptr);

/*!
 * @function dispatch_mach_msg_get_msg
 * Returns the message buffer underlying a dispatch mach message object.
 *
 * @param message	The dispatch mach message object to query.
 * @param size_ptr	A pointer to a size_t variable to be filled with the
 *					size of the message buffer, or NULL.
 * @result			Pointer to message buffer underlying the object.
 */
API_AVAILABLE(macos(10.9), ios(7.0))
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
mach_msg_header_t*
dispatch_mach_msg_get_msg(dispatch_mach_msg_t message,
		size_t *_Nullable size_ptr);

#ifdef __BLOCKS__
/*!
 * @typedef dispatch_mach_handler_t
 * Prototype of dispatch mach channel handler blocks.
 *
 * @param reason	Reason the handler was invoked.
 * @param message	Message object that was sent or received.
 * @param error		Mach error code for the send operation.
 */
typedef void (^dispatch_mach_handler_t)(dispatch_mach_reason_t reason,
		dispatch_mach_msg_t _Nullable message, mach_error_t error);

/*!
 * @function dispatch_mach_create
 * Create a dispatch mach channel to asynchronously receive and send mach
 * messages.
 *
 * The specified handler will be called with the corresponding reason parameter
 * for each message received and for each message that was successfully sent,
 * that failed to be sent, or was not sent; as well as when a barrier block
 * has completed, or when channel connection, reconnection or cancellation has
 * taken effect.
 *
 * Dispatch mach channels are created in a disconnected state, they must be
 * connected via dispatch_mach_connect() to begin receiving and sending
 * messages.
 *
 * @param label
 * An optional string label to attach to the channel. The string is not copied,
 * if it is non-NULL it must point to storage that remains valid for the
 * lifetime of the channel object. May be NULL.
 *
 * @param queue
 * The target queue of the channel, where the handler and barrier blocks will
 * be submitted.
 *
 * @param handler
 * The handler block to submit when a message has been sent or received.
 *
 * @result
 * The newly created dispatch mach channel.
 */
API_AVAILABLE(macos(10.9), ios(6.0))
DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
DISPATCH_NONNULL3 DISPATCH_NOTHROW
dispatch_mach_t
dispatch_mach_create(const char *_Nullable label,
		dispatch_queue_t _Nullable queue, dispatch_mach_handler_t handler);
#endif

/*!
 * @typedef dispatch_mach_handler_function_t
 * Prototype of dispatch mach channel handler functions.
 *
 * @param context	Application-defined context parameter.
 * @param reason	Reason the handler was invoked.
 * @param message	Message object that was sent or received.
 * @param error		Mach error code for the send operation.
 */
typedef void (*dispatch_mach_handler_function_t)(void *_Nullable context,
		dispatch_mach_reason_t reason, dispatch_mach_msg_t _Nullable message,
		mach_error_t error);

/*!
 * @function dispatch_mach_create_f
 * Create a dispatch mach channel to asynchronously receive and send mach
 * messages.
 *
 * The specified handler will be called with the corresponding reason parameter
 * for each message received and for each message that was successfully sent,
 * that failed to be sent, or was not sent; as well as when a barrier block
 * has completed, or when channel connection, reconnection or cancellation has
 * taken effect.
 *
 * Dispatch mach channels are created in a disconnected state, they must be
 * connected via dispatch_mach_connect() to begin receiving and sending
 * messages.
 *
 * @param label
 * An optional string label to attach to the channel. The string is not copied,
 * if it is non-NULL it must point to storage that remains valid for the
 * lifetime of the channel object. May be NULL.
 *
 * @param queue
 * The target queue of the channel, where the handler and barrier blocks will
 * be submitted.
 *
 * @param context
 * The application-defined context to pass to the handler.
 *
 * @param handler
 * The handler function to submit when a message has been sent or received.
 *
 * @result
 * The newly created dispatch mach channel.
 */
API_AVAILABLE(macos(10.9), ios(6.0))
DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
DISPATCH_NONNULL4 DISPATCH_NOTHROW
dispatch_mach_t
dispatch_mach_create_f(const char *_Nullable label,
		dispatch_queue_t _Nullable queue, void *_Nullable context,
		dispatch_mach_handler_function_t handler);

/*!
 * @function dispatch_mach_connect
 * Connect a mach channel to the specified receive and send rights.
 *
 * This function must only be called once during the lifetime of a channel, it
 * will initiate message reception and perform any already submitted message
 * sends or barrier operations.
 *
 * @param channel
 * The mach channel to connect.
 *
 * @param receive
 * The receive right to associate with the channel. May be MACH_PORT_NULL.
 *
 * @param send
 * The send right to associate with the channel. May be MACH_PORT_NULL.
 *
 * @param checkin
 * An optional message object encapsulating the initial check-in message to send
 * upon channel connection. The check-in message is sent immediately before the
 * first message submitted via dispatch_mach_send(). The message object will be
 * retained until the initial send operation is complete (or not peformed due
 * to channel cancellation or reconnection) and the channel handler has
 * returned. May be NULL.
 */
API_AVAILABLE(macos(10.9), ios(6.0))
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
void
dispatch_mach_connect(dispatch_mach_t channel, mach_port_t receive,
		mach_port_t send, dispatch_mach_msg_t _Nullable checkin);

/*!
 * @function dispatch_mach_reconnect
 * Reconnect a mach channel to the specified send right.
 *
 * Disconnects the channel from the current send right, interrupts any pending
 * message sends (and returns the messages as unsent), and reconnects the
 * channel to a new send right.
 *
 * The application must wait for the channel handler to be invoked with
 * DISPATCH_MACH_DISCONNECTED before releasing the previous send right.
 *
 * @param channel
 * The mach channel to reconnect.
 *
 * @param send
 * The new send right to associate with the channel. May be MACH_PORT_NULL.
 *
 * @param checkin
 * An optional message object encapsulating the initial check-in message to send
 * upon channel reconnection. The check-in message is sent immediately before
 * the first message submitted via dispatch_mach_send() after this function
 * returns. The message object will be retained until the initial send operation
 * is complete (or not peformed due to channel cancellation or reconnection)
 * and the channel handler has returned. May be NULL.
 */
API_AVAILABLE(macos(10.9), ios(6.0))
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
void
dispatch_mach_reconnect(dispatch_mach_t channel, mach_port_t send,
		dispatch_mach_msg_t _Nullable checkin);

/*!
 * @function dispatch_mach_cancel
 * Cancel a mach channel, preventing any further messages from being sent or
 * received.
 *
 * The application must wait for the channel handler to be invoked with
 * DISPATCH_MACH_DISCONNECTED before releasing the underlying send and receive
 * rights.
 *
 * Note: explicit cancellation of mach channels is required, no implicit
 *       cancellation takes place on release of the last application reference
 *       to the channel object. Failure to cancel will cause the channel and
 *       its associated resources to be leaked.
 *
 * @param channel
 * The mach channel to cancel.
 */
API_AVAILABLE(macos(10.9), ios(6.0))
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
void
dispatch_mach_cancel(dispatch_mach_t channel);

/*!
 * @function dispatch_mach_send
 * Asynchronously send a message encapsulated in a dispatch mach message object
 * to the specified mach channel.
 *
 * Unless the message is being sent to a send-once right (as determined by the
 * presence of MACH_MSG_TYPE_MOVE_SEND_ONCE in the message header remote bits),
 * the message header remote port is set to the channel send right before the
 * send operation is performed.
 *
 * If the message expects a direct reply (as determined by the presence of
 * MACH_MSG_TYPE_MAKE_SEND_ONCE in the message header local bits) the receive
 * right specified in the message header local port will be monitored until a
 * reply message (or a send-once notification) is received, or the channel is
 * canceled. Hence the application must wait for the channel handler to be
 * invoked with a DISPATCH_MACH_DISCONNECTED message before releasing that
 * receive right.
 *
 * If the message send operation is attempted but the channel is canceled
 * before the send operation succesfully completes, the message returned to the
 * channel handler with DISPATCH_MACH_MESSAGE_NOT_SENT may be the result of a
 * pseudo-receive operation. If the message expected a direct reply, the
 * receive right originally specified in the message header local port will
 * returned in a DISPATCH_MACH_DISCONNECTED message.
 *
 * @param channel
 * The mach channel to which to send the message.
 *
 * @param message
 * The message object encapsulating the message to send. The object will be
 * retained until the send operation is complete and the channel handler has
 * returned. The storage underlying the message object may be modified by the
 * send operation.
 *
 * @param options
 * Additional send options to pass to mach_msg() when performing the send
 * operation.
 */
API_AVAILABLE(macos(10.9), ios(6.0))
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NOTHROW
void
dispatch_mach_send(dispatch_mach_t channel, dispatch_mach_msg_t message,
		mach_msg_option_t options);

/*!
 * @function dispatch_mach_send_with_result
 * Asynchronously send a message encapsulated in a dispatch mach message object
 * to the specified mach channel. If an immediate send can be performed, return
 * its result via out parameters.
 *
 * Unless the message is being sent to a send-once right (as determined by the
 * presence of MACH_MSG_TYPE_MOVE_SEND_ONCE in the message header remote bits),
 * the message header remote port is set to the channel send right before the
 * send operation is performed.
 *
 * If the message expects a direct reply (as determined by the presence of
 * MACH_MSG_TYPE_MAKE_SEND_ONCE in the message header local bits) the receive
 * right specified in the message header local port will be monitored until a
 * reply message (or a send-once notification) is received, or the channel is
 * canceled. Hence the application must wait for the channel handler to be
 * invoked with a DISPATCH_MACH_DISCONNECTED message before releasing that
 * receive right.
 *
 * If the message send operation is attempted but the channel is canceled
 * before the send operation succesfully completes, the message returned to the
 * channel handler with DISPATCH_MACH_MESSAGE_NOT_SENT may be the result of a
 * pseudo-receive operation. If the message expected a direct reply, the
 * receive right originally specified in the message header local port will
 * returned in a DISPATCH_MACH_DISCONNECTED message.
 *
 * If an immediate send could be performed, returns the resulting reason
 * (e.g. DISPATCH_MACH_MESSAGE_SENT) and possible error to the caller in the
 * send_result and send_error out parameters (instead of via the channel
 * handler), in which case the passed-in message and associated resources
 * can be disposed of synchronously.
 *
 * If a deferred send is required, returns DISPATCH_MACH_NEEDS_DEFERRED_SEND
 * in the send_result out parameter to indicate that the passed-in message has
 * been retained and associated resources must not be disposed of until the
 * message is returned asynchronusly via the channel handler.
 *
 * @param channel
 * The mach channel to which to send the message.
 *
 * @param message
 * The message object encapsulating the message to send. Unless an immediate
 * send could be performed, the object will be retained until the asynchronous
 * send operation is complete and the channel handler has returned. The storage
 * underlying the message object may be modified by the send operation.
 *
 * @param options
 * Additional send options to pass to mach_msg() when performing the send
 * operation.
 *
 * @param send_flags
 * Flags to configure the send operation. Must be 0 for now.
 *
 * @param send_result
 * Out parameter to return the result of the immediate send attempt.
 * If a deferred send is required, returns DISPATCH_MACH_NEEDS_DEFERRED_SEND.
 * Must not be NULL.
 *
 * @param send_error
 * Out parameter to return the error from the immediate send attempt.
 * If a deferred send is required, returns 0. Must not be NULL.
 */
API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL5
DISPATCH_NONNULL6 DISPATCH_NOTHROW
void
dispatch_mach_send_with_result(dispatch_mach_t channel,
		dispatch_mach_msg_t message, mach_msg_option_t options,
		dispatch_mach_send_flags_t send_flags,
		dispatch_mach_reason_t *send_result, mach_error_t *send_error);

/*!
 * @function dispatch_mach_send_and_wait_for_reply
 * Synchronously send a message encapsulated in a dispatch mach message object
 * to the specified mach channel and wait for a reply.
 *
 * Unless the message is being sent to a send-once right (as determined by the
 * presence of MACH_MSG_TYPE_MOVE_SEND_ONCE in the message header remote bits),
 * the message header remote port is set to the channel send right before the
 * send operation is performed.
 *
 * The message is required to expect a direct reply (as determined by the
 * presence of MACH_MSG_TYPE_MAKE_SEND_ONCE in the message header local bits)
 * and this function will not complete until the receive right specified in the
 * message header local port receives a reply message (or a send-once
 * notification) which will be returned, or until that receive right is
 * destroyed in response to the channel being canceled, in which case NULL will
 * be returned.
 * In all these cases the application must wait for the channel handler to
 * be invoked with a DISPATCH_MACH_REPLY_RECEIVED or DISPATCH_MACH_DISCONNECTED
 * message before releasing that receive right.
 *
 * Alternatively, the application may specify MACH_PORT_NULL in the header local
 * port to indicate that the channel should create and manage the reply receive
 * right internally, including destroying it upon channel cancellation.
 * This is a more efficient mode of operation as no asynchronous operations are
 * required to return the receive right (i.e. the channel handler will not be
 * called as described above).
 *
 * If the message send operation is attempted but the channel is canceled
 * before the send operation succesfully completes, the message returned to the
 * channel handler with DISPATCH_MACH_MESSAGE_NOT_SENT may be the result of a
 * pseudo-receive operation. The receive right originally specified in the
 * message header local port will returned in a DISPATCH_MACH_DISCONNECTED
 * message (unless it was MACH_PORT_NULL).
 *
 * @param channel
 * The mach channel to which to send the message.
 *
 * @param message
 * The message object encapsulating the message to send. The object will be
 * retained until the send operation is complete and the channel handler has
 * returned. The storage underlying the message object may be modified by the
 * send operation.
 *
 * @param options
 * Additional send options to pass to mach_msg() when performing the send
 * operation.
 *
 * @result
 * The received reply message object, or NULL if the channel was canceled.
 */
API_AVAILABLE(macos(10.11), ios(9.0))
DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NOTHROW
dispatch_mach_msg_t _Nullable
dispatch_mach_send_and_wait_for_reply(dispatch_mach_t channel,
		dispatch_mach_msg_t message, mach_msg_option_t options);

/*!
 * @function dispatch_mach_send_with_result_and_wait_for_reply
 * Synchronously send a message encapsulated in a dispatch mach message object
 * to the specified mach channel and wait for a reply. If an immediate send can
 * be performed, return its result via out parameters.
 *
 * Unless the message is being sent to a send-once right (as determined by the
 * presence of MACH_MSG_TYPE_MOVE_SEND_ONCE in the message header remote bits),
 * the message header remote port is set to the channel send right before the
 * send operation is performed.
 *
 * The message is required to expect a direct reply (as determined by the
 * presence of MACH_MSG_TYPE_MAKE_SEND_ONCE in the message header local bits)
 * and this function will not complete until the receive right specified in the
 * message header local port receives a reply message (or a send-once
 * notification) which will be returned, or until that receive right is
 * destroyed in response to the channel being canceled, in which case NULL will
 * be returned.
 * In all these cases the application must wait for the channel handler to
 * be invoked with a DISPATCH_MACH_REPLY_RECEIVED or DISPATCH_MACH_DISCONNECTED
 * message before releasing that receive right.
 *
 * Alternatively, the application may specify MACH_PORT_NULL in the header local
 * port to indicate that the channel should create and manage the reply receive
 * right internally, including destroying it upon channel cancellation.
 * This is a more efficient mode of operation as no asynchronous operations are
 * required to return the receive right (i.e. the channel handler will not be
 * called as described above).
 *
 * If the message send operation is attempted but the channel is canceled
 * before the send operation succesfully completes, the message returned to the
 * channel handler with DISPATCH_MACH_MESSAGE_NOT_SENT may be the result of a
 * pseudo-receive operation. The receive right originally specified in the
 * message header local port will returned in a DISPATCH_MACH_DISCONNECTED
 * message (unless it was MACH_PORT_NULL).
 *
 * If an immediate send could be performed, returns the resulting reason
 * (e.g. DISPATCH_MACH_MESSAGE_SENT) and possible error to the caller in the
 * send_result and send_error out parameters (instead of via the channel
 * handler), in which case the passed-in message and associated resources
 * can be disposed of synchronously.
 *
 * If a deferred send is required, returns DISPATCH_MACH_NEEDS_DEFERRED_SEND
 * in the send_result out parameter to indicate that the passed-in message has
 * been retained and associated resources must not be disposed of until the
 * message is returned asynchronusly via the channel handler.
 *
 * @param channel
 * The mach channel to which to send the message.
 *
 * @param message
 * The message object encapsulating the message to send. Unless an immediate
 * send could be performed, the object will be retained until the asynchronous
 * send operation is complete and the channel handler has returned. The storage
 * underlying the message object may be modified by the send operation.
 *
 * @param options
 * Additional send options to pass to mach_msg() when performing the send
 * operation.
 *
 * @param send_flags
 * Flags to configure the send operation. Must be 0 for now.
 *
 * @param send_result
 * Out parameter to return the result of the immediate send attempt.
 * If a deferred send is required, returns DISPATCH_MACH_NEEDS_DEFERRED_SEND.
 * Must not be NULL.
 *
 * @param send_error
 * Out parameter to return the error from the immediate send attempt.
 * If a deferred send is required, returns 0. Must not be NULL.
 *
 * @result
 * The received reply message object, or NULL if the channel was canceled.
 */
API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL5 DISPATCH_NONNULL6
DISPATCH_NOTHROW
dispatch_mach_msg_t _Nullable
dispatch_mach_send_with_result_and_wait_for_reply(dispatch_mach_t channel,
		dispatch_mach_msg_t message, mach_msg_option_t options,
		dispatch_mach_send_flags_t send_flags,
		dispatch_mach_reason_t *send_result, mach_error_t *send_error);

#ifdef __BLOCKS__
/*!
 * @function dispatch_mach_send_barrier
 * Submit a send barrier to the specified mach channel. Messages submitted to
 * the channel before the barrier will be sent before the barrier block is
 * executed, and messages submitted to the channel after the barrier will only
 * be sent once the barrier block has completed and the channel handler
 * invocation for the barrier has returned.
 *
 * @param channel
 * The mach channel to which to submit the barrier.
 *
 * @param barrier
 * The barrier block to submit to the channel target queue.
 */
API_AVAILABLE(macos(10.9), ios(6.0))
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
void
dispatch_mach_send_barrier(dispatch_mach_t channel, dispatch_block_t barrier);
#endif

/*!
 * @function dispatch_mach_send_barrier_f
 * Submit a send barrier to the specified mach channel. Messages submitted to
 * the channel before the barrier will be sent before the barrier block is
 * executed, and messages submitted to the channel after the barrier will only
 * be sent once the barrier block has completed and the channel handler
 * invocation for the barrier has returned.
 *
 * @param channel
 * The mach channel to which to submit the barrier.
 *
 * @param context
 * The application-defined context parameter to pass to the function.
 *
 * @param barrier
 * The barrier function to submit to the channel target queue.
 */
API_AVAILABLE(macos(10.9), ios(6.0))
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
void
dispatch_mach_send_barrier_f(dispatch_mach_t channel, void *_Nullable context,
		dispatch_function_t barrier);

#ifdef __BLOCKS__
/*!
 * @function dispatch_mach_receive_barrier
 * Submit a receive barrier to the specified mach channel. Channel handlers for
 * messages received by the channel after the receive barrier has been
 * submitted will only be invoked once the barrier block has completed and the
 * channel handler invocation for the barrier has returned.
 *
 * @param channel
 * The mach channel to which to submit the receive barrier.
 *
 * @param barrier
 * The barrier block to submit to the channel target queue.
 */
API_AVAILABLE(macos(10.9), ios(6.0))
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
void
dispatch_mach_receive_barrier(dispatch_mach_t channel,
		dispatch_block_t barrier);
#endif

/*!
 * @function dispatch_mach_receive_barrier_f
 * Submit a receive barrier to the specified mach channel. Channel handlers for
 * messages received by the channel after the receive barrier has been
 * submitted will only be invoked once the barrier block has completed and the
 * channel handler invocation for the barrier has returned.
 *
 * @param channel
 * The mach channel to which to submit the receive barrier.
 *
 * @param context
 * The application-defined context parameter to pass to the function.
 *
 * @param barrier
 * The barrier function to submit to the channel target queue.
 */
API_AVAILABLE(macos(10.9), ios(6.0))
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
void
dispatch_mach_receive_barrier_f(dispatch_mach_t channel, void *_Nullable context,
		dispatch_function_t barrier);

/*!
 * @function dispatch_mach_get_checkin_port
 * Returns the port specified in the message header remote port of the check-in
 * message passed to the most recent invocation of dispatch_mach_connect() or
 * dispatch_mach_reconnect() for the provided mach channel (irrespective of the
 * completion of the (re)connect or check-in operations in question).
 *
 * Returns MACH_PORT_NULL if dispatch_mach_connect() has not yet been called or
 * if the most recently specified check-in message was NULL, and MACH_PORT_DEAD
 * if the channel has been canceled.
 *
 * It is the responsibility of the application to ensure that the port
 * specified in a check-in message remains valid at the time this function is
 * called.
 *
 * @param channel
 * The mach channel to query.
 *
 * @result
 * The most recently specified check-in port for the channel.
 */
API_AVAILABLE(macos(10.9), ios(6.0))
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
mach_port_t
dispatch_mach_get_checkin_port(dispatch_mach_t channel);

// SPI for libxpc
/*
 * Type for the callback for receipt of asynchronous replies to
 * dispatch_mach_send_with_result_and_async_reply_4libxpc().
 */
typedef void (*_Nonnull dispatch_mach_async_reply_callback_t)(void *context,
		dispatch_mach_reason_t reason, dispatch_mach_msg_t message);

API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
typedef const struct dispatch_mach_xpc_hooks_s {
#define DISPATCH_MACH_XPC_HOOKS_VERSION     3
	unsigned long version;

	/* Fields available in version 1. */

	/*
	 * Called to handle a Mach message event inline if possible. Returns true
	 * if the event was handled, false if the event should be delivered to the
	 * channel event handler. The implementation should not make any assumptions
	 * about the thread in which the function is called and cannot assume that
	 * invocations of this function are serialized relative to each other or
	 * relative to the channel's event handler function. In addition, the
	 * handler must not throw an exception or call out to any code that might
	 * throw an exception.
	 */
	bool (* _Nonnull dmxh_direct_message_handler)(void *_Nullable context,
			dispatch_mach_reason_t reason, dispatch_mach_msg_t message,
			mach_error_t error);

	/* Fields available in version 2. */

	/*
	 * Gets the queue to which a reply to a message sent using
	 * dispatch_mach_send_with_result_and_async_reply_4libxpc() should be
	 * delivered. The msg_context argument is the value of the do_ctxt field
	 * of the outgoing message, as returned by dispatch_get_context(). If this
	 * function returns NULL, the reply will be delivered to the channel queue.
	 * This function should not make any assumptions about the thread on which
	 * it is called and, since it may be called more than once per message, it
	 * should execute as quickly as possible and not attempt to synchronize with
	 * other code.
	 */
	dispatch_queue_t _Nullable (*_Nonnull dmxh_msg_context_reply_queue)(
			void *_Nonnull msg_context);

	/*
	 * Called when a reply to a message sent by
	 * dispatch_mach_send_with_result_and_async_reply_4libxpc() is received. The
	 * message argument points to the reply message and the context argument is
	 * the context value passed to dispatch_mach_create_4libxpc() when creating
	 * the Mach channel. The handler is called on the queue that is returned by
	 * dmxh_msg_context_reply_queue() when the reply is received or if the
	 * channel is disconnected. The reason argument is
	 * DISPATCH_MACH_MESSAGE_RECEIVED if a reply has been received or
	 * DISPATCH_MACH_ASYNC_WAITER_DISCONNECTED if the channel has been
	 * disconnected. Refer to the documentation for
	 * dispatch_mach_send_with_result_and_async_reply_4libxpc() for more
	 * details.
	 */
	dispatch_mach_async_reply_callback_t dmxh_async_reply_handler;

	/* Fields available in version 3. */
	/**
	 * Called once when the Mach channel has been activated. If this function
	 * returns true, a DISPATCH_MACH_SIGTERM_RECEIVED notification will be
	 * delivered to the channel's event handler when a SIGTERM is received.
	 */
	bool (* _Nullable dmxh_enable_sigterm_notification)(
			void *_Nullable context);
} *dispatch_mach_xpc_hooks_t;

#define DISPATCH_MACH_XPC_SUPPORTS_ASYNC_REPLIES(hooks) ((hooks)->version >= 2)

/*!
 * @function dispatch_mach_hooks_install_4libxpc
 *
 * @abstract
 * installs XPC callbacks for dispatch Mach channels.
 *
 * @discussion
 * In order to improve the performance of the XPC/dispatch interface, it is
 * sometimes useful for dispatch to be able to call directly into XPC. The
 * channel hooks structure should be initialized with pointers to XPC callback
 * functions, or NULL for callbacks that XPC does not support. The version
 * number in the structure must be set to reflect the fields that have been
 * initialized. This function may be called only once.
 *
 * @param hooks
 * A pointer to the channel hooks structure. This must remain valid once set.
 */
API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
void
dispatch_mach_hooks_install_4libxpc(dispatch_mach_xpc_hooks_t hooks);

/*!
 * @function dispatch_mach_create_4libxpc
 * Create a dispatch mach channel to asynchronously receive and send mach
 * messages, specifically for libxpc.
 *
 * The specified handler will be called with the corresponding reason parameter
 * for each message received and for each message that was successfully sent,
 * that failed to be sent, or was not sent; as well as when a barrier block
 * has completed, or when channel connection, reconnection or cancellation has
 * taken effect. However, the handler will not be called for messages that 
 * were passed to the XPC hooks dmxh_direct_message_handler function if that
 * function returned true.
 *
 * Dispatch mach channels are created in a disconnected state, they must be
 * connected via dispatch_mach_connect() to begin receiving and sending
 * messages.
 *
 * @param label
 * An optional string label to attach to the channel. The string is not copied,
 * if it is non-NULL it must point to storage that remains valid for the
 * lifetime of the channel object. May be NULL.
 *
 * @param queue
 * The target queue of the channel, where the handler and barrier blocks will
 * be submitted.
 *
 * @param context
 * The application-defined context to pass to the handler.
 *
 * @param handler
 * The handler function to submit when a message has been sent or received.
 *
 * @result
 * The newly created dispatch mach channel.
 */
API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
DISPATCH_NONNULL4 DISPATCH_NOTHROW
dispatch_mach_t
dispatch_mach_create_4libxpc(const char *_Nullable label,
		dispatch_queue_t _Nullable queue, void *_Nullable context,
		dispatch_mach_handler_function_t handler);

/*!
 * @function dispatch_mach_send_with_result_and_async_reply_4libxpc
 * SPI for XPC that asynchronously sends a message encapsulated in a dispatch
 * mach message object to the specified mach channel. If an immediate send can
 * be performed, returns its result via out parameters.
 *
 * The reply message is processed on the queue returned by the
 * dmxh_msg_context_reply_queue function in the dispatch_mach_xpc_hooks_s
 * structure, which is called with a single argument whose value is the
 * do_ctxt field of the message argument to this function. The reply message is
 * delivered to the dmxh_async_reply_handler hook function instead of being 
 * passed to the channel event handler.
 *
 * If the dmxh_msg_context_reply_queue function is not implemented or returns
 * NULL, the reply message is delivered to the channel event handler on the
 * channel queue.
 *
 * Unless the message is being sent to a send-once right (as determined by the
 * presence of MACH_MSG_TYPE_MOVE_SEND_ONCE in the message header remote bits),
 * the message header remote port is set to the channel send right before the
 * send operation is performed.
 *
 * The message is required to expect a direct reply (as determined by the
 * presence of MACH_MSG_TYPE_MAKE_SEND_ONCE in the message header local bits).
 * The receive right specified in the message header local port will be
 * monitored until a reply message (or a send-once notification) is received, or
 * the channel is canceled. Hence the application must wait for the reply
 * to be received or for a DISPATCH_MACH_ASYNC_WAITER_DISCONNECTED message
 * before releasing that receive right.
 *
 * If the message send operation is attempted but the channel is canceled
 * before the send operation succesfully completes, the message returned to the
 * channel handler with DISPATCH_MACH_MESSAGE_NOT_SENT may be the result of a
 * pseudo-receive operation and the receive right originally specified in the
 * message header local port will be returned in a
 * DISPATCH_MACH_ASYNC_WAITER_DISCONNECTED message.
 *
 * If an immediate send could be performed, returns the resulting reason
 * (e.g. DISPATCH_MACH_MESSAGE_SENT) and possible error to the caller in the
 * send_result and send_error out parameters (instead of via the channel
 * handler), in which case the passed-in message and associated resources
 * can be disposed of synchronously.
 *
 * If a deferred send is required, returns DISPATCH_MACH_NEEDS_DEFERRED_SEND
 * in the send_result out parameter to indicate that the passed-in message has
 * been retained and associated resources must not be disposed of until the
 * message is returned asynchronusly via the channel handler.
 *
 * @param channel
 * The mach channel to which to send the message.
 *
 * @param message
 * The message object encapsulating the message to send. Unless an immediate
 * send could be performed, the object will be retained until the asynchronous
 * send operation is complete and the channel handler has returned. The storage
 * underlying the message object may be modified by the send operation.
 *
 * @param options
 * Additional send options to pass to mach_msg() when performing the send
 * operation.
 *
 * @param send_flags
 * Flags to configure the send operation. Must be 0 for now.
 *
 * @param send_result
 * Out parameter to return the result of the immediate send attempt.
 * If a deferred send is required, returns DISPATCH_MACH_NEEDS_DEFERRED_SEND.
 * Must not be NULL.
 *
 * @param send_error
 * Out parameter to return the error from the immediate send attempt.
 * If a deferred send is required, returns 0. Must not be NULL.
 */
API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL5
DISPATCH_NONNULL6 DISPATCH_NOTHROW
void
dispatch_mach_send_with_result_and_async_reply_4libxpc(dispatch_mach_t channel,
		dispatch_mach_msg_t message, mach_msg_option_t options,
		dispatch_mach_send_flags_t send_flags,
		dispatch_mach_reason_t *send_result, mach_error_t *send_error);

DISPATCH_ASSUME_NONNULL_END

#endif // DISPATCH_MACH_SPI

__END_DECLS

#endif