private/mach_private.h

   1 /*
   2  * Copyright (c) 2012-2013 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_APACHE_LICENSE_HEADER_START@
   5  *
   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
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  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.
  17  *
  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_MACH_PRIVATE__
  28 #define __DISPATCH_MACH_PRIVATE__
  29
  30 #ifndef __DISPATCH_INDIRECT__
  31 #error "Please #include <dispatch/dispatch.h> instead of this file directly."
  32 #include <dispatch/base.h> // for HeaderDoc
  33 #endif
  34
  35 __BEGIN_DECLS
  36
  37 #if DISPATCH_MACH_SPI
  38
  39 #define DISPATCH_MACH_SPI_VERSION 20160505
  40
  41 #include <mach/mach.h>
  42
  43 DISPATCH_ASSUME_NONNULL_BEGIN
  44
  45 /*!
  46  * @functiongroup Dispatch Mach Channel SPI
  47  *
  48  * IMPORTANT: This is Libsystem-internal SPI not intended for general use and
  49  * is subject to change at any time without warning.
  50  */
  51
  52 /*!
  53  * @typedef dispatch_mach_t
  54  * A dispatch mach channel asynchronously recevives and sends mach messages.
  55  */
  56 DISPATCH_DECL(dispatch_mach);
  57
  58 /*!
  59  * @typedef dispatch_mach_reason_t
  60  * Reasons for a mach channel handler to be invoked, or the result of an
  61  * immediate send attempt.
  62  *
  63  * @const DISPATCH_MACH_CONNECTED
  64  * The channel has been connected. The first handler invocation on a channel
  65  * after calling dispatch_mach_connect() will have this reason.
  66  *
  67  * @const DISPATCH_MACH_MESSAGE_RECEIVED
  68  * A message was received, it is passed in the message parameter.
  69  *
  70  * @const DISPATCH_MACH_MESSAGE_SENT
  71  * A message was sent, it is passed in the message parameter (so that associated
  72  * resources can be disposed of).
  73  *
  74  * @const DISPATCH_MACH_MESSAGE_SEND_FAILED
  75  * A message failed to be sent, it is passed in the message parameter (so that
  76  * associated resources can be disposed of), along with the error code from
  77  * mach_msg().
  78  *
  79  * @const DISPATCH_MACH_MESSAGE_NOT_SENT
  80  * A message was not sent due to the channel being canceled or reconnected, it
  81  * is passed in the message parameter (so that associated resources can be
  82  * disposed of).
  83  *
  84  * @const DISPATCH_MACH_BARRIER_COMPLETED
  85  * A barrier block has finished executing.
  86  *
  87  * @const DISPATCH_MACH_DISCONNECTED
  88  * The channel has been disconnected by a call to dispatch_mach_reconnect() or
  89  * dispatch_mach_cancel(), an empty message is passed in the message parameter
  90  * (so that associated port rights can be disposed of).
  91  * The message header will contain either a remote port with a previously
  92  * connected send right, or a local port with a previously connected receive
  93  * right (if the channel was canceled), or a local port with a receive right
  94  * that was being monitored for a direct reply to a message previously sent to
  95  * the channel (if no reply was received).
  96  *
  97  * @const DISPATCH_MACH_CANCELED
  98  * The channel has been canceled.
  99  *
 100  * @const DISPATCH_MACH_REPLY_RECEIVED
 101  * A synchronous reply to a call to dispatch_mach_send_and_wait_for_reply() has
 102  * been received on another thread, an empty message is passed in the message
 103  * parameter (so that associated port rights can be disposed of).
 104  * The message header will contain a local port with a receive right associated
 105  * with the reply to the message that was synchronously sent to the channel.
 106  *
 107  * @const DISPATCH_MACH_NEEDS_DEFERRED_SEND
 108  * The message could not be sent synchronously. Only returned from a send with
 109  * result operation and never passed to a channel handler. Indicates that the
 110  * message passed to the send operation must not be disposed of until it is
 111  * returned via the channel handler.
 112  */
 113 DISPATCH_ENUM(dispatch_mach_reason, unsigned long,
 114         DISPATCH_MACH_CONNECTED = 1,
 115         DISPATCH_MACH_MESSAGE_RECEIVED,
 116         DISPATCH_MACH_MESSAGE_SENT,
 117         DISPATCH_MACH_MESSAGE_SEND_FAILED,
 118         DISPATCH_MACH_MESSAGE_NOT_SENT,
 119         DISPATCH_MACH_BARRIER_COMPLETED,
 120         DISPATCH_MACH_DISCONNECTED,
 121         DISPATCH_MACH_CANCELED,
 122         DISPATCH_MACH_REPLY_RECEIVED,
 123         DISPATCH_MACH_NEEDS_DEFERRED_SEND,
 124         DISPATCH_MACH_REASON_LAST, /* unused */
 125 );
 126
 127 /*!
 128  * @typedef dispatch_mach_send_flags_t
 129  * Flags that can be passed to the *with_flags send functions.
 130  */
 131 DISPATCH_ENUM(dispatch_mach_send_flags, unsigned long,
 132         DISPATCH_MACH_SEND_DEFAULT = 0,
 133 );
 134
 135 /*!
 136  * @typedef dispatch_mach_trailer_t
 137  * Trailer type of mach message received by dispatch mach channels
 138  */
 139
 140 typedef mach_msg_context_trailer_t dispatch_mach_trailer_t;
 141
 142 /*!
 143  * @constant DISPATCH_MACH_RECEIVE_MAX_INLINE_MESSAGE_SIZE
 144  * Maximum size of a message that can be received inline by a dispatch mach
 145  * channel, reception of larger messages requires an extra roundtrip through
 146  * the kernel.
 147  */
 148
 149 #define DISPATCH_MACH_RECEIVE_MAX_INLINE_MESSAGE_SIZE \
 150                 (0x4000 - sizeof(dispatch_mach_trailer_t))
 151
 152 /*!
 153  * @typedef dispatch_mach_msg_t
 154  * A dispatch mach message encapsulates messages received or sent with dispatch
 155  * mach channels.
 156  */
 157 DISPATCH_DECL(dispatch_mach_msg);
 158
 159 /*!
 160  * @typedef dispatch_mach_msg_destructor_t
 161  * Dispatch mach message object destructors.
 162  *
 163  * @const DISPATCH_MACH_MSG_DESTRUCTOR_DEFAULT
 164  * Message buffer storage is internal to the object, if a buffer is supplied
 165  * during object creation, its contents are copied.
 166  *
 167  * @const DISPATCH_MACH_MSG_DESTRUCTOR_FREE
 168  * Message buffer will be deallocated with free(3).
 169  *
 170  * @const DISPATCH_MACH_MSG_DESTRUCTOR_FREE
 171  * Message buffer will be deallocated with vm_deallocate.
 172  */
 173 DISPATCH_ENUM(dispatch_mach_msg_destructor, unsigned int,
 174         DISPATCH_MACH_MSG_DESTRUCTOR_DEFAULT = 0,
 175         DISPATCH_MACH_MSG_DESTRUCTOR_FREE,
 176         DISPATCH_MACH_MSG_DESTRUCTOR_VM_DEALLOCATE,
 177 );
 178
 179 /*!
 180  * @function dispatch_mach_msg_create
 181  * Creates a dispatch mach message object, either with a newly allocated message
 182  * buffer of given size, or from an existing message buffer that will be
 183  * deallocated with the specified destructor when the object is released.
 184  *
 185  * If a non-NULL reference to a pointer is provided in 'msg_ptr', it is filled
 186  * with the location of the (possibly newly allocated) message buffer.
 187  *
 188  * It is the responsibility of the application to ensure that it does not modify
 189  * the underlying message buffer once the dispatch mach message object is passed
 190  * to other dispatch mach API.
 191  *
 192  * @param msg                   The message buffer to create the message object from.
 193  *                                              If 'destructor' is DISPATCH_MACH_MSG_DESTRUCTOR_DEFAULT,
 194  *                                              this argument may be NULL to leave the newly allocated
 195  *                                              message buffer zero-initialized.
 196  * @param size                  The size of the message buffer.
 197  *                                              Must be >= sizeof(mach_msg_header_t)
 198  * @param destructor    The destructor to use to deallocate the message buffer
 199  *                                              when the object is released.
 200  * @param msg_ptr               A pointer to a pointer variable to be filled with the
 201  *                                              location of the (possibly newly allocated) message
 202  *                                              buffer, or NULL.
 203  * @result                              A newly created dispatch mach message object.
 204  */
 205 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
 206 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 207 DISPATCH_NOTHROW
 208 dispatch_mach_msg_t
 209 dispatch_mach_msg_create(mach_msg_header_t *_Nullable msg, size_t size,
 210                 dispatch_mach_msg_destructor_t destructor,
 211                 mach_msg_header_t *_Nonnull *_Nullable msg_ptr);
 212
 213 /*!
 214  * @function dispatch_mach_msg_get_msg
 215  * Returns the message buffer underlying a dispatch mach message object.
 216  *
 217  * @param message       The dispatch mach message object to query.
 218  * @param size_ptr      A pointer to a size_t variable to be filled with the
 219  *                                      size of the message buffer, or NULL.
 220  * @result                      Pointer to message buffer underlying the object.
 221  */
 222 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
 223 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 224 mach_msg_header_t*
 225 dispatch_mach_msg_get_msg(dispatch_mach_msg_t message,
 226                 size_t *_Nullable size_ptr);
 227
 228 #ifdef __BLOCKS__
 229 /*!
 230  * @typedef dispatch_mach_handler_t
 231  * Prototype of dispatch mach channel handler blocks.
 232  *
 233  * @param reason        Reason the handler was invoked.
 234  * @param message       Message object that was sent or received.
 235  * @param error         Mach error code for the send operation.
 236  */
 237 typedef void (^dispatch_mach_handler_t)(dispatch_mach_reason_t reason,
 238                 dispatch_mach_msg_t _Nullable message, mach_error_t error);
 239
 240 /*!
 241  * @function dispatch_mach_create
 242  * Create a dispatch mach channel to asynchronously receive and send mach
 243  * messages.
 244  *
 245  * The specified handler will be called with the corresponding reason parameter
 246  * for each message received and for each message that was successfully sent,
 247  * that failed to be sent, or was not sent; as well as when a barrier block
 248  * has completed, or when channel connection, reconnection or cancellation has
 249  * taken effect.
 250  *
 251  * Dispatch mach channels are created in a disconnected state, they must be
 252  * connected via dispatch_mach_connect() to begin receiving and sending
 253  * messages.
 254  *
 255  * @param label
 256  * An optional string label to attach to the channel. The string is not copied,
 257  * if it is non-NULL it must point to storage that remains valid for the
 258  * lifetime of the channel object. May be NULL.
 259  *
 260  * @param queue
 261  * The target queue of the channel, where the handler and barrier blocks will
 262  * be submitted.
 263  *
 264  * @param handler
 265  * The handler block to submit when a message has been sent or received.
 266  *
 267  * @result
 268  * The newly created dispatch mach channel.
 269  */
 270 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 271 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 272 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 273 dispatch_mach_t
 274 dispatch_mach_create(const char *_Nullable label,
 275                 dispatch_queue_t _Nullable queue, dispatch_mach_handler_t handler);
 276 #endif
 277
 278 /*!
 279  * @typedef dispatch_mach_handler_function_t
 280  * Prototype of dispatch mach channel handler functions.
 281  *
 282  * @param context       Application-defined context parameter.
 283  * @param reason        Reason the handler was invoked.
 284  * @param message       Message object that was sent or received.
 285  * @param error         Mach error code for the send operation.
 286  */
 287 typedef void (*dispatch_mach_handler_function_t)(void *_Nullable context,
 288                 dispatch_mach_reason_t reason, dispatch_mach_msg_t _Nullable message,
 289                 mach_error_t error);
 290
 291 /*!
 292  * @function dispatch_mach_create_f
 293  * Create a dispatch mach channel to asynchronously receive and send mach
 294  * messages.
 295  *
 296  * The specified handler will be called with the corresponding reason parameter
 297  * for each message received and for each message that was successfully sent,
 298  * that failed to be sent, or was not sent; as well as when a barrier block
 299  * has completed, or when channel connection, reconnection or cancellation has
 300  * taken effect.
 301  *
 302  * Dispatch mach channels are created in a disconnected state, they must be
 303  * connected via dispatch_mach_connect() to begin receiving and sending
 304  * messages.
 305  *
 306  * @param label
 307  * An optional string label to attach to the channel. The string is not copied,
 308  * if it is non-NULL it must point to storage that remains valid for the
 309  * lifetime of the channel object. May be NULL.
 310  *
 311  * @param queue
 312  * The target queue of the channel, where the handler and barrier blocks will
 313  * be submitted.
 314  *
 315  * @param context
 316  * The application-defined context to pass to the handler.
 317  *
 318  * @param handler
 319  * The handler function to submit when a message has been sent or received.
 320  *
 321  * @result
 322  * The newly created dispatch mach channel.
 323  */
 324 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 325 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 326 DISPATCH_NONNULL4 DISPATCH_NOTHROW
 327 dispatch_mach_t
 328 dispatch_mach_create_f(const char *_Nullable label,
 329                 dispatch_queue_t _Nullable queue, void *_Nullable context,
 330                 dispatch_mach_handler_function_t handler);
 331
 332 /*!
 333  * @function dispatch_mach_connect
 334  * Connect a mach channel to the specified receive and send rights.
 335  *
 336  * This function must only be called once during the lifetime of a channel, it
 337  * will initiate message reception and perform any already submitted message
 338  * sends or barrier operations.
 339  *
 340  * @param channel
 341  * The mach channel to connect.
 342  *
 343  * @param receive
 344  * The receive right to associate with the channel. May be MACH_PORT_NULL.
 345  *
 346  * @param send
 347  * The send right to associate with the channel. May be MACH_PORT_NULL.
 348  *
 349  * @param checkin
 350  * An optional message object encapsulating the initial check-in message to send
 351  * upon channel connection. The check-in message is sent immediately before the
 352  * first message submitted via dispatch_mach_send(). The message object will be
 353  * retained until the initial send operation is complete (or not peformed due
 354  * to channel cancellation or reconnection) and the channel handler has
 355  * returned. May be NULL.
 356  */
 357 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 358 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 359 void
 360 dispatch_mach_connect(dispatch_mach_t channel, mach_port_t receive,
 361                 mach_port_t send, dispatch_mach_msg_t _Nullable checkin);
 362
 363 /*!
 364  * @function dispatch_mach_reconnect
 365  * Reconnect a mach channel to the specified send right.
 366  *
 367  * Disconnects the channel from the current send right, interrupts any pending
 368  * message sends (and returns the messages as unsent), and reconnects the
 369  * channel to a new send right.
 370  *
 371  * The application must wait for the channel handler to be invoked with
 372  * DISPATCH_MACH_DISCONNECTED before releasing the previous send right.
 373  *
 374  * @param channel
 375  * The mach channel to reconnect.
 376  *
 377  * @param send
 378  * The new send right to associate with the channel. May be MACH_PORT_NULL.
 379  *
 380  * @param checkin
 381  * An optional message object encapsulating the initial check-in message to send
 382  * upon channel reconnection. The check-in message is sent immediately before
 383  * the first message submitted via dispatch_mach_send() after this function
 384  * returns. The message object will be retained until the initial send operation
 385  * is complete (or not peformed due to channel cancellation or reconnection)
 386  * and the channel handler has returned. May be NULL.
 387  */
 388 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 389 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 390 void
 391 dispatch_mach_reconnect(dispatch_mach_t channel, mach_port_t send,
 392                 dispatch_mach_msg_t _Nullable checkin);
 393
 394 /*!
 395  * @function dispatch_mach_cancel
 396  * Cancel a mach channel, preventing any further messages from being sent or
 397  * received.
 398  *
 399  * The application must wait for the channel handler to be invoked with
 400  * DISPATCH_MACH_DISCONNECTED before releasing the underlying send and receive
 401  * rights.
 402  *
 403  * Note: explicit cancellation of mach channels is required, no implicit
 404  *       cancellation takes place on release of the last application reference
 405  *       to the channel object. Failure to cancel will cause the channel and
 406  *       its associated resources to be leaked.
 407  *
 408  * @param channel
 409  * The mach channel to cancel.
 410  */
 411 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 412 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 413 void
 414 dispatch_mach_cancel(dispatch_mach_t channel);
 415
 416 /*!
 417  * @function dispatch_mach_send
 418  * Asynchronously send a message encapsulated in a dispatch mach message object
 419  * to the specified mach channel.
 420  *
 421  * Unless the message is being sent to a send-once right (as determined by the
 422  * presence of MACH_MSG_TYPE_MOVE_SEND_ONCE in the message header remote bits),
 423  * the message header remote port is set to the channel send right before the
 424  * send operation is performed.
 425  *
 426  * If the message expects a direct reply (as determined by the presence of
 427  * MACH_MSG_TYPE_MAKE_SEND_ONCE in the message header local bits) the receive
 428  * right specified in the message header local port will be monitored until a
 429  * reply message (or a send-once notification) is received, or the channel is
 430  * canceled. Hence the application must wait for the channel handler to be
 431  * invoked with a DISPATCH_MACH_DISCONNECTED message before releasing that
 432  * receive right.
 433  *
 434  * If the message send operation is attempted but the channel is canceled
 435  * before the send operation succesfully completes, the message returned to the
 436  * channel handler with DISPATCH_MACH_MESSAGE_NOT_SENT may be the result of a
 437  * pseudo-receive operation. If the message expected a direct reply, the
 438  * receive right originally specified in the message header local port will
 439  * returned in a DISPATCH_MACH_DISCONNECTED message.
 440  *
 441  * @param channel
 442  * The mach channel to which to send the message.
 443  *
 444  * @param message
 445  * The message object encapsulating the message to send. The object will be
 446  * retained until the send operation is complete and the channel handler has
 447  * returned. The storage underlying the message object may be modified by the
 448  * send operation.
 449  *
 450  * @param options
 451  * Additional send options to pass to mach_msg() when performing the send
 452  * operation.
 453  */
 454 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 455 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NOTHROW
 456 void
 457 dispatch_mach_send(dispatch_mach_t channel, dispatch_mach_msg_t message,
 458                 mach_msg_option_t options);
 459
 460 /*!
 461  * @function dispatch_mach_send_with_result
 462  * Asynchronously send a message encapsulated in a dispatch mach message object
 463  * to the specified mach channel. If an immediate send can be performed, return
 464  * its result via out parameters.
 465  *
 466  * Unless the message is being sent to a send-once right (as determined by the
 467  * presence of MACH_MSG_TYPE_MOVE_SEND_ONCE in the message header remote bits),
 468  * the message header remote port is set to the channel send right before the
 469  * send operation is performed.
 470  *
 471  * If the message expects a direct reply (as determined by the presence of
 472  * MACH_MSG_TYPE_MAKE_SEND_ONCE in the message header local bits) the receive
 473  * right specified in the message header local port will be monitored until a
 474  * reply message (or a send-once notification) is received, or the channel is
 475  * canceled. Hence the application must wait for the channel handler to be
 476  * invoked with a DISPATCH_MACH_DISCONNECTED message before releasing that
 477  * receive right.
 478  *
 479  * If the message send operation is attempted but the channel is canceled
 480  * before the send operation succesfully completes, the message returned to the
 481  * channel handler with DISPATCH_MACH_MESSAGE_NOT_SENT may be the result of a
 482  * pseudo-receive operation. If the message expected a direct reply, the
 483  * receive right originally specified in the message header local port will
 484  * returned in a DISPATCH_MACH_DISCONNECTED message.
 485  *
 486  * If an immediate send could be performed, returns the resulting reason
 487  * (e.g. DISPATCH_MACH_MESSAGE_SENT) and possible error to the caller in the
 488  * send_result and send_error out parameters (instead of via the channel
 489  * handler), in which case the passed-in message and associated resources
 490  * can be disposed of synchronously.
 491  *
 492  * If a deferred send is required, returns DISPATCH_MACH_NEEDS_DEFERRED_SEND
 493  * in the send_result out parameter to indicate that the passed-in message has
 494  * been retained and associated resources must not be disposed of until the
 495  * message is returned asynchronusly via the channel handler.
 496  *
 497  * @param channel
 498  * The mach channel to which to send the message.
 499  *
 500  * @param message
 501  * The message object encapsulating the message to send. Unless an immediate
 502  * send could be performed, the object will be retained until the asynchronous
 503  * send operation is complete and the channel handler has returned. The storage
 504  * underlying the message object may be modified by the send operation.
 505  *
 506  * @param options
 507  * Additional send options to pass to mach_msg() when performing the send
 508  * operation.
 509  *
 510  * @param send_flags
 511  * Flags to configure the send operation. Must be 0 for now.
 512  *
 513  * @param send_result
 514  * Out parameter to return the result of the immediate send attempt.
 515  * If a deferred send is required, returns DISPATCH_MACH_NEEDS_DEFERRED_SEND.
 516  * Must not be NULL.
 517  *
 518  * @param send_error
 519  * Out parameter to return the error from the immediate send attempt.
 520  * If a deferred send is required, returns 0. Must not be NULL.
 521  */
 522 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
 523 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
 524 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL5
 525 DISPATCH_NONNULL6 DISPATCH_NOTHROW
 526 void
 527 dispatch_mach_send_with_result(dispatch_mach_t channel,
 528                 dispatch_mach_msg_t message, mach_msg_option_t options,
 529                 dispatch_mach_send_flags_t send_flags,
 530                 dispatch_mach_reason_t *send_result, mach_error_t *send_error);
 531
 532 /*!
 533  * @function dispatch_mach_send_and_wait_for_reply
 534  * Synchronously send a message encapsulated in a dispatch mach message object
 535  * to the specified mach channel and wait for a reply.
 536  *
 537  * Unless the message is being sent to a send-once right (as determined by the
 538  * presence of MACH_MSG_TYPE_MOVE_SEND_ONCE in the message header remote bits),
 539  * the message header remote port is set to the channel send right before the
 540  * send operation is performed.
 541  *
 542  * The message is required to expect a direct reply (as determined by the
 543  * presence of MACH_MSG_TYPE_MAKE_SEND_ONCE in the message header local bits)
 544  * and this function will not complete until the receive right specified in the
 545  * message header local port receives a reply message (or a send-once
 546  * notification) which will be returned, or until that receive right is
 547  * destroyed in response to the channel being canceled, in which case NULL will
 548  * be returned.
 549  * In all these cases the application must wait for the channel handler to
 550  * be invoked with a DISPATCH_MACH_REPLY_RECEIVED or DISPATCH_MACH_DISCONNECTED
 551  * message before releasing that receive right.
 552  *
 553  * Alternatively, the application may specify MACH_PORT_NULL in the header local
 554  * port to indicate that the channel should create and manage the reply receive
 555  * right internally, including destroying it upon channel cancellation.
 556  * This is a more efficient mode of operation as no asynchronous operations are
 557  * required to return the receive right (i.e. the channel handler will not be
 558  * called as described above).
 559  *
 560  * If the message send operation is attempted but the channel is canceled
 561  * before the send operation succesfully completes, the message returned to the
 562  * channel handler with DISPATCH_MACH_MESSAGE_NOT_SENT may be the result of a
 563  * pseudo-receive operation. The receive right originally specified in the
 564  * message header local port will returned in a DISPATCH_MACH_DISCONNECTED
 565  * message (unless it was MACH_PORT_NULL).
 566  *
 567  * @param channel
 568  * The mach channel to which to send the message.
 569  *
 570  * @param message
 571  * The message object encapsulating the message to send. The object will be
 572  * retained until the send operation is complete and the channel handler has
 573  * returned. The storage underlying the message object may be modified by the
 574  * send operation.
 575  *
 576  * @param options
 577  * Additional send options to pass to mach_msg() when performing the send
 578  * operation.
 579  *
 580  * @result
 581  * The received reply message object, or NULL if the channel was canceled.
 582  */
 583 __OSX_AVAILABLE_STARTING(__MAC_10_11,__IPHONE_9_0)
 584 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 585 DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NOTHROW
 586 dispatch_mach_msg_t _Nullable
 587 dispatch_mach_send_and_wait_for_reply(dispatch_mach_t channel,
 588                 dispatch_mach_msg_t message, mach_msg_option_t options);
 589
 590 /*!
 591  * @function dispatch_mach_send_with_result_and_wait_for_reply
 592  * Synchronously send a message encapsulated in a dispatch mach message object
 593  * to the specified mach channel and wait for a reply. If an immediate send can
 594  * be performed, return its result via out parameters.
 595  *
 596  * Unless the message is being sent to a send-once right (as determined by the
 597  * presence of MACH_MSG_TYPE_MOVE_SEND_ONCE in the message header remote bits),
 598  * the message header remote port is set to the channel send right before the
 599  * send operation is performed.
 600  *
 601  * The message is required to expect a direct reply (as determined by the
 602  * presence of MACH_MSG_TYPE_MAKE_SEND_ONCE in the message header local bits)
 603  * and this function will not complete until the receive right specified in the
 604  * message header local port receives a reply message (or a send-once
 605  * notification) which will be returned, or until that receive right is
 606  * destroyed in response to the channel being canceled, in which case NULL will
 607  * be returned.
 608  * In all these cases the application must wait for the channel handler to
 609  * be invoked with a DISPATCH_MACH_REPLY_RECEIVED or DISPATCH_MACH_DISCONNECTED
 610  * message before releasing that receive right.
 611  *
 612  * Alternatively, the application may specify MACH_PORT_NULL in the header local
 613  * port to indicate that the channel should create and manage the reply receive
 614  * right internally, including destroying it upon channel cancellation.
 615  * This is a more efficient mode of operation as no asynchronous operations are
 616  * required to return the receive right (i.e. the channel handler will not be
 617  * called as described above).
 618  *
 619  * If the message send operation is attempted but the channel is canceled
 620  * before the send operation succesfully completes, the message returned to the
 621  * channel handler with DISPATCH_MACH_MESSAGE_NOT_SENT may be the result of a
 622  * pseudo-receive operation. The receive right originally specified in the
 623  * message header local port will returned in a DISPATCH_MACH_DISCONNECTED
 624  * message (unless it was MACH_PORT_NULL).
 625  *
 626  * If an immediate send could be performed, returns the resulting reason
 627  * (e.g. DISPATCH_MACH_MESSAGE_SENT) and possible error to the caller in the
 628  * send_result and send_error out parameters (instead of via the channel
 629  * handler), in which case the passed-in message and associated resources
 630  * can be disposed of synchronously.
 631  *
 632  * If a deferred send is required, returns DISPATCH_MACH_NEEDS_DEFERRED_SEND
 633  * in the send_result out parameter to indicate that the passed-in message has
 634  * been retained and associated resources must not be disposed of until the
 635  * message is returned asynchronusly via the channel handler.
 636  *
 637  * @param channel
 638  * The mach channel to which to send the message.
 639  *
 640  * @param message
 641  * The message object encapsulating the message to send. Unless an immediate
 642  * send could be performed, the object will be retained until the asynchronous
 643  * send operation is complete and the channel handler has returned. The storage
 644  * underlying the message object may be modified by the send operation.
 645  *
 646  * @param options
 647  * Additional send options to pass to mach_msg() when performing the send
 648  * operation.
 649  *
 650  * @param send_flags
 651  * Flags to configure the send operation. Must be 0 for now.
 652  *
 653  * @param send_result
 654  * Out parameter to return the result of the immediate send attempt.
 655  * If a deferred send is required, returns DISPATCH_MACH_NEEDS_DEFERRED_SEND.
 656  * Must not be NULL.
 657  *
 658  * @param send_error
 659  * Out parameter to return the error from the immediate send attempt.
 660  * If a deferred send is required, returns 0. Must not be NULL.
 661  *
 662  * @result
 663  * The received reply message object, or NULL if the channel was canceled.
 664  */
 665 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
 666 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
 667 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 668 DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL5 DISPATCH_NONNULL6
 669 DISPATCH_NOTHROW
 670 dispatch_mach_msg_t _Nullable
 671 dispatch_mach_send_with_result_and_wait_for_reply(dispatch_mach_t channel,
 672                 dispatch_mach_msg_t message, mach_msg_option_t options,
 673                 dispatch_mach_send_flags_t send_flags,
 674                 dispatch_mach_reason_t *send_result, mach_error_t *send_error);
 675
 676 #ifdef __BLOCKS__
 677 /*!
 678  * @function dispatch_mach_send_barrier
 679  * Submit a send barrier to the specified mach channel. Messages submitted to
 680  * the channel before the barrier will be sent before the barrier block is
 681  * executed, and messages submitted to the channel after the barrier will only
 682  * be sent once the barrier block has completed and the channel handler
 683  * invocation for the barrier has returned.
 684  *
 685  * @param channel
 686  * The mach channel to which to submit the barrier.
 687  *
 688  * @param barrier
 689  * The barrier block to submit to the channel target queue.
 690  */
 691 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 692 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 693 void
 694 dispatch_mach_send_barrier(dispatch_mach_t channel, dispatch_block_t barrier);
 695 #endif
 696
 697 /*!
 698  * @function dispatch_mach_send_barrier_f
 699  * Submit a send barrier to the specified mach channel. Messages submitted to
 700  * the channel before the barrier will be sent before the barrier block is
 701  * executed, and messages submitted to the channel after the barrier will only
 702  * be sent once the barrier block has completed and the channel handler
 703  * invocation for the barrier has returned.
 704  *
 705  * @param channel
 706  * The mach channel to which to submit the barrier.
 707  *
 708  * @param context
 709  * The application-defined context parameter to pass to the function.
 710  *
 711  * @param barrier
 712  * The barrier function to submit to the channel target queue.
 713  */
 714 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 715 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 716 void
 717 dispatch_mach_send_barrier_f(dispatch_mach_t channel, void *_Nullable context,
 718                 dispatch_function_t barrier);
 719
 720 #ifdef __BLOCKS__
 721 /*!
 722  * @function dispatch_mach_receive_barrier
 723  * Submit a receive barrier to the specified mach channel. Channel handlers for
 724  * messages received by the channel after the receive barrier has been
 725  * submitted will only be invoked once the barrier block has completed and the
 726  * channel handler invocation for the barrier has returned.
 727  *
 728  * @param channel
 729  * The mach channel to which to submit the receive barrier.
 730  *
 731  * @param barrier
 732  * The barrier block to submit to the channel target queue.
 733  */
 734 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 735 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 736 void
 737 dispatch_mach_receive_barrier(dispatch_mach_t channel,
 738                 dispatch_block_t barrier);
 739 #endif
 740
 741 /*!
 742  * @function dispatch_mach_receive_barrier_f
 743  * Submit a receive barrier to the specified mach channel. Channel handlers for
 744  * messages received by the channel after the receive barrier has been
 745  * submitted will only be invoked once the barrier block has completed and the
 746  * channel handler invocation for the barrier has returned.
 747  *
 748  * @param channel
 749  * The mach channel to which to submit the receive barrier.
 750  *
 751  * @param context
 752  * The application-defined context parameter to pass to the function.
 753  *
 754  * @param barrier
 755  * The barrier function to submit to the channel target queue.
 756  */
 757 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 758 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 759 void
 760 dispatch_mach_receive_barrier_f(dispatch_mach_t channel, void *_Nullable context,
 761                 dispatch_function_t barrier);
 762
 763 /*!
 764  * @function dispatch_mach_get_checkin_port
 765  * Returns the port specified in the message header remote port of the check-in
 766  * message passed to the most recent invocation of dispatch_mach_connect() or
 767  * dispatch_mach_reconnect() for the provided mach channel (irrespective of the
 768  * completion of the (re)connect or check-in operations in question).
 769  *
 770  * Returns MACH_PORT_NULL if dispatch_mach_connect() has not yet been called or
 771  * if the most recently specified check-in message was NULL, and MACH_PORT_DEAD
 772  * if the channel has been canceled.
 773  *
 774  * It is the responsibility of the application to ensure that the port
 775  * specified in a check-in message remains valid at the time this function is
 776  * called.
 777  *
 778  * @param channel
 779  * The mach channel to query.
 780  *
 781  * @result
 782  * The most recently specified check-in port for the channel.
 783  */
 784 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 785 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 786 mach_port_t
 787 dispatch_mach_get_checkin_port(dispatch_mach_t channel);
 788
 789 DISPATCH_ASSUME_NONNULL_END
 790
 791 #endif // DISPATCH_MACH_SPI
 792
 793 __END_DECLS
 794
 795 #endif