private/io_private.h

   1 /*
   2  * Copyright (c) 2009-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_IO_PRIVATE__
  28 #define __DISPATCH_IO_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 DISPATCH_ASSUME_NONNULL_BEGIN
  36
  37 __BEGIN_DECLS
  38
  39 /*!
  40  * @function dispatch_read_f
  41  * Schedule a read operation for asynchronous execution on the specified file
  42  * descriptor. The specified handler is enqueued with the data read from the
  43  * file descriptor when the operation has completed or an error occurs.
  44  *
  45  * The data object passed to the handler will be automatically released by the
  46  * system when the handler returns. It is the responsibility of the application
  47  * to retain, concatenate or copy the data object if it is needed after the
  48  * handler returns.
  49  *
  50  * The data object passed to the handler will only contain as much data as is
  51  * currently available from the file descriptor (up to the specified length).
  52  *
  53  * If an unrecoverable error occurs on the file descriptor, the handler will be
  54  * enqueued with the appropriate error code along with a data object of any data
  55  * that could be read successfully.
  56  *
  57  * An invocation of the handler with an error code of zero and an empty data
  58  * object indicates that EOF was reached.
  59  *
  60  * The system takes control of the file descriptor until the handler is
  61  * enqueued, and during this time file descriptor flags such as O_NONBLOCK will
  62  * be modified by the system on behalf of the application. It is an error for
  63  * the application to modify a file descriptor directly while it is under the
  64  * control of the system, but it may create additional dispatch I/O convenience
  65  * operations or dispatch I/O channels associated with that file descriptor.
  66  *
  67  * @param fd            The file descriptor from which to read the data.
  68  * @param length        The length of data to read from the file descriptor,
  69  *                      or SIZE_MAX to indicate that all of the data currently
  70  *                      available from the file descriptor should be read.
  71  * @param queue         The dispatch queue to which the handler should be
  72  *                      submitted.
  73  * @param context       The application-defined context parameter to pass to
  74  *                      the handler function.
  75  * @param handler       The handler to enqueue when data is ready to be
  76  *                      delivered.
  77  *              param context   Application-defined context parameter.
  78  *              param data      The data read from the file descriptor.
  79  *              param error     An errno condition for the read operation or
  80  *                              zero if the read was successful.
  81  */
  82 API_AVAILABLE(macos(10.9), ios(7.0))
  83 DISPATCH_EXPORT DISPATCH_NONNULL3 DISPATCH_NONNULL5 DISPATCH_NOTHROW
  84 void
  85 dispatch_read_f(dispatch_fd_t fd,
  86         size_t length,
  87         dispatch_queue_t queue,
  88         void *_Nullable context,
  89         void (*handler)(void *_Nullable context, dispatch_data_t data, int error));
  90
  91 /*!
  92  * @function dispatch_write_f
  93  * Schedule a write operation for asynchronous execution on the specified file
  94  * descriptor. The specified handler is enqueued when the operation has
  95  * completed or an error occurs.
  96  *
  97  * If an unrecoverable error occurs on the file descriptor, the handler will be
  98  * enqueued with the appropriate error code along with the data that could not
  99  * be successfully written.
 100  *
 101  * An invocation of the handler with an error code of zero indicates that the
 102  * data was fully written to the channel.
 103  *
 104  * The system takes control of the file descriptor until the handler is
 105  * enqueued, and during this time file descriptor flags such as O_NONBLOCK will
 106  * be modified by the system on behalf of the application. It is an error for
 107  * the application to modify a file descriptor directly while it is under the
 108  * control of the system, but it may create additional dispatch I/O convenience
 109  * operations or dispatch I/O channels associated with that file descriptor.
 110  *
 111  * @param fd            The file descriptor to which to write the data.
 112  * @param data          The data object to write to the file descriptor.
 113  * @param queue         The dispatch queue to which the handler should be
 114  *                      submitted.
 115  * @param context       The application-defined context parameter to pass to
 116  *                      the handler function.
 117  * @param handler       The handler to enqueue when the data has been written.
 118  *              param context   Application-defined context parameter.
 119  *              param data      The data that could not be written to the I/O
 120  *                              channel, or NULL.
 121  *              param error     An errno condition for the write operation or
 122  *                              zero if the write was successful.
 123  */
 124 API_AVAILABLE(macos(10.9), ios(7.0))
 125 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NONNULL3 DISPATCH_NONNULL5
 126 DISPATCH_NOTHROW
 127 void
 128 dispatch_write_f(dispatch_fd_t fd,
 129         dispatch_data_t data,
 130         dispatch_queue_t queue,
 131         void *_Nullable context,
 132         void (*handler)(void *_Nullable context, dispatch_data_t _Nullable data,
 133                         int error));
 134
 135 /*!
 136  * @function dispatch_io_create_f
 137  * Create a dispatch I/O channel associated with a file descriptor. The system
 138  * takes control of the file descriptor until the channel is closed, an error
 139  * occurs on the file descriptor or all references to the channel are released.
 140  * At that time the specified cleanup handler will be enqueued and control over
 141  * the file descriptor relinquished.
 142  *
 143  * While a file descriptor is under the control of a dispatch I/O channel, file
 144  * descriptor flags such as O_NONBLOCK will be modified by the system on behalf
 145  * of the application. It is an error for the application to modify a file
 146  * descriptor directly while it is under the control of a dispatch I/O channel,
 147  * but it may create additional channels associated with that file descriptor.
 148  *
 149  * @param type  The desired type of I/O channel (DISPATCH_IO_STREAM
 150  *              or DISPATCH_IO_RANDOM).
 151  * @param fd    The file descriptor to associate with the I/O channel.
 152  * @param queue The dispatch queue to which the handler should be submitted.
 153  * @param context       The application-defined context parameter to pass to
 154  *                      the cleanup handler function.
 155  * @param cleanup_handler       The handler to enqueue when the system
 156  *                              relinquishes control over the file descriptor.
 157  *      param context           Application-defined context parameter.
 158  *      param error             An errno condition if control is relinquished
 159  *                              because channel creation failed, zero otherwise.
 160  * @result      The newly created dispatch I/O channel or NULL if an error
 161  *              occurred (invalid type specified).
 162  */
 163 API_AVAILABLE(macos(10.9), ios(7.0))
 164 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 165 DISPATCH_NOTHROW
 166 dispatch_io_t
 167 dispatch_io_create_f(dispatch_io_type_t type,
 168         dispatch_fd_t fd,
 169         dispatch_queue_t queue,
 170         void *_Nullable context,
 171         void (*cleanup_handler)(void *_Nullable context, int error));
 172
 173 /*!
 174  * @function dispatch_io_create_with_path_f
 175  * Create a dispatch I/O channel associated with a path name. The specified
 176  * path, oflag and mode parameters will be passed to open(2) when the first I/O
 177  * operation on the channel is ready to execute and the resulting file
 178  * descriptor will remain open and under the control of the system until the
 179  * channel is closed, an error occurs on the file descriptor or all references
 180  * to the channel are released. At that time the file descriptor will be closed
 181  * and the specified cleanup handler will be enqueued.
 182  *
 183  * @param type  The desired type of I/O channel (DISPATCH_IO_STREAM
 184  *              or DISPATCH_IO_RANDOM).
 185  * @param path  The absolute path to associate with the I/O channel.
 186  * @param oflag The flags to pass to open(2) when opening the file at
 187  *              path.
 188  * @param mode  The mode to pass to open(2) when creating the file at
 189  *              path (i.e. with flag O_CREAT), zero otherwise.
 190  * @param queue The dispatch queue to which the handler should be
 191  *              submitted.
 192  * @param context       The application-defined context parameter to pass to
 193  *                      the cleanup handler function.
 194  * @param cleanup_handler       The handler to enqueue when the system
 195  *                              has closed the file at path.
 196  *      param context           Application-defined context parameter.
 197  *      param error             An errno condition if control is relinquished
 198  *                              because channel creation or opening of the
 199  *                              specified file failed, zero otherwise.
 200  * @result      The newly created dispatch I/O channel or NULL if an error
 201  *              occurred (invalid type or non-absolute path specified).
 202  */
 203 API_AVAILABLE(macos(10.9), ios(7.0))
 204 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED
 205 DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 206 dispatch_io_t
 207 dispatch_io_create_with_path_f(dispatch_io_type_t type,
 208         const char *path, int oflag, mode_t mode,
 209         dispatch_queue_t queue,
 210         void *_Nullable context,
 211         void (*cleanup_handler)(void *_Nullable context, int error));
 212
 213 /*!
 214  * @function dispatch_io_create_with_io_f
 215  * Create a new dispatch I/O channel from an existing dispatch I/O channel.
 216  * The new channel inherits the file descriptor or path name associated with
 217  * the existing channel, but not its channel type or policies.
 218  *
 219  * If the existing channel is associated with a file descriptor, control by the
 220  * system over that file descriptor is extended until the new channel is also
 221  * closed, an error occurs on the file descriptor, or all references to both
 222  * channels are released. At that time the specified cleanup handler will be
 223  * enqueued and control over the file descriptor relinquished.
 224  *
 225  * While a file descriptor is under the control of a dispatch I/O channel, file
 226  * descriptor flags such as O_NONBLOCK will be modified by the system on behalf
 227  * of the application. It is an error for the application to modify a file
 228  * descriptor directly while it is under the control of a dispatch I/O channel,
 229  * but it may create additional channels associated with that file descriptor.
 230  *
 231  * @param type  The desired type of I/O channel (DISPATCH_IO_STREAM
 232  *              or DISPATCH_IO_RANDOM).
 233  * @param io    The existing channel to create the new I/O channel from.
 234  * @param queue The dispatch queue to which the handler should be submitted.
 235  * @param context       The application-defined context parameter to pass to
 236  *                      the cleanup handler function.
 237  * @param cleanup_handler       The handler to enqueue when the system
 238  *                              relinquishes control over the file descriptor
 239  *                              (resp. closes the file at path) associated with
 240  *                              the existing channel.
 241  *      param context           Application-defined context parameter.
 242  *      param error             An errno condition if control is relinquished
 243  *                              because channel creation failed, zero otherwise.
 244  * @result      The newly created dispatch I/O channel or NULL if an error
 245  *              occurred (invalid type specified).
 246  */
 247 API_AVAILABLE(macos(10.9), ios(7.0))
 248 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED
 249 DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 250 dispatch_io_t
 251 dispatch_io_create_with_io_f(dispatch_io_type_t type,
 252         dispatch_io_t io,
 253         dispatch_queue_t queue,
 254         void *_Nullable context,
 255         void (*cleanup_handler)(void *_Nullable context, int error));
 256
 257 /*!
 258  * @typedef dispatch_io_handler_function_t
 259  * The prototype of I/O handler functions for dispatch I/O operations.
 260  *
 261  * @param context       Application-defined context parameter.
 262  * @param done          A flag indicating whether the operation is complete.
 263  * @param data          The data object to be handled.
 264  * @param error         An errno condition for the operation.
 265  */
 266 typedef void (*dispatch_io_handler_function_t)(void *_Nullable context,
 267         bool done, dispatch_data_t _Nullable data, int error);
 268
 269 /*!
 270  * @function dispatch_io_read_f
 271  * Schedule a read operation for asynchronous execution on the specified I/O
 272  * channel. The I/O handler is enqueued one or more times depending on the
 273  * general load of the system and the policy specified on the I/O channel.
 274  *
 275  * Any data read from the channel is described by the dispatch data object
 276  * passed to the I/O handler. This object will be automatically released by the
 277  * system when the I/O handler returns. It is the responsibility of the
 278  * application to retain, concatenate or copy the data object if it is needed
 279  * after the I/O handler returns.
 280  *
 281  * Dispatch I/O handlers are not reentrant. The system will ensure that no new
 282  * I/O handler instance is invoked until the previously enqueued handler
 283  * function has returned.
 284  *
 285  * An invocation of the I/O handler with the done flag set indicates that the
 286  * read operation is complete and that the handler will not be enqueued again.
 287  *
 288  * If an unrecoverable error occurs on the I/O channel's underlying file
 289  * descriptor, the I/O handler will be enqueued with the done flag set, the
 290  * appropriate error code and a NULL data object.
 291  *
 292  * An invocation of the I/O handler with the done flag set, an error code of
 293  * zero and an empty data object indicates that EOF was reached.
 294  *
 295  * @param channel       The dispatch I/O channel from which to read the data.
 296  * @param offset        The offset relative to the channel position from which
 297  *                      to start reading (only for DISPATCH_IO_RANDOM).
 298  * @param length        The length of data to read from the I/O channel, or
 299  *                      SIZE_MAX to indicate that data should be read until EOF
 300  *                      is reached.
 301  * @param queue         The dispatch queue to which the I/O handler should be
 302  *                      submitted.
 303  * @param context       The application-defined context parameter to pass to
 304  *                      the handler function.
 305  * @param io_handler    The I/O handler to enqueue when data is ready to be
 306  *                      delivered.
 307  *      param context   Application-defined context parameter.
 308  *      param done      A flag indicating whether the operation is complete.
 309  *      param data      An object with the data most recently read from the
 310  *                      I/O channel as part of this read operation, or NULL.
 311  *      param error     An errno condition for the read operation or zero if
 312  *                      the read was successful.
 313  */
 314 API_AVAILABLE(macos(10.9), ios(7.0))
 315 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL4 DISPATCH_NONNULL6
 316 DISPATCH_NOTHROW
 317 void
 318 dispatch_io_read_f(dispatch_io_t channel,
 319         off_t offset,
 320         size_t length,
 321         dispatch_queue_t queue,
 322         void *_Nullable context,
 323         dispatch_io_handler_function_t io_handler);
 324
 325 /*!
 326  * @function dispatch_io_write_f
 327  * Schedule a write operation for asynchronous execution on the specified I/O
 328  * channel. The I/O handler is enqueued one or more times depending on the
 329  * general load of the system and the policy specified on the I/O channel.
 330  *
 331  * Any data remaining to be written to the I/O channel is described by the
 332  * dispatch data object passed to the I/O handler. This object will be
 333  * automatically released by the system when the I/O handler returns. It is the
 334  * responsibility of the application to retain, concatenate or copy the data
 335  * object if it is needed after the I/O handler returns.
 336  *
 337  * Dispatch I/O handlers are not reentrant. The system will ensure that no new
 338  * I/O handler instance is invoked until the previously enqueued handler
 339  * function has returned.
 340  *
 341  * An invocation of the I/O handler with the done flag set indicates that the
 342  * write operation is complete and that the handler will not be enqueued again.
 343  *
 344  * If an unrecoverable error occurs on the I/O channel's underlying file
 345  * descriptor, the I/O handler will be enqueued with the done flag set, the
 346  * appropriate error code and an object containing the data that could not be
 347  * written.
 348  *
 349  * An invocation of the I/O handler with the done flag set and an error code of
 350  * zero indicates that the data was fully written to the channel.
 351  *
 352  * @param channel       The dispatch I/O channel on which to write the data.
 353  * @param offset        The offset relative to the channel position from which
 354  *                      to start writing (only for DISPATCH_IO_RANDOM).
 355  * @param data          The data to write to the I/O channel. The data object
 356  *                      will be retained by the system until the write operation
 357  *                      is complete.
 358  * @param queue         The dispatch queue to which the I/O handler should be
 359  *                      submitted.
 360  * @param context       The application-defined context parameter to pass to
 361  *                      the handler function.
 362  * @param io_handler    The I/O handler to enqueue when data has been delivered.
 363  *      param context   Application-defined context parameter.
 364  *      param done      A flag indicating whether the operation is complete.
 365  *      param data      An object of the data remaining to be
 366  *                      written to the I/O channel as part of this write
 367  *                      operation, or NULL.
 368  *      param error     An errno condition for the write operation or zero
 369  *                      if the write was successful.
 370  */
 371 API_AVAILABLE(macos(10.9), ios(7.0))
 372 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NONNULL4
 373 DISPATCH_NONNULL6 DISPATCH_NOTHROW
 374 void
 375 dispatch_io_write_f(dispatch_io_t channel,
 376         off_t offset,
 377         dispatch_data_t data,
 378         dispatch_queue_t queue,
 379         void *_Nullable context,
 380         dispatch_io_handler_function_t io_handler);
 381
 382 /*!
 383  * @function dispatch_io_barrier_f
 384  * Schedule a barrier operation on the specified I/O channel; all previously
 385  * scheduled operations on the channel will complete before the provided
 386  * barrier function is enqueued onto the global queue determined by the
 387  * channel's target queue, and no subsequently scheduled operations will start
 388  * until the barrier function has returned.
 389  *
 390  * If multiple channels are associated with the same file descriptor, a barrier
 391  * operation scheduled on any of these channels will act as a barrier across all
 392  * channels in question, i.e. all previously scheduled operations on any of the
 393  * channels will complete before the barrier function is enqueued, and no
 394  * operations subsequently scheduled on any of the channels will start until the
 395  * barrier function has returned.
 396  *
 397  * While the barrier function is running, it may safely operate on the channel's
 398  * underlying file descriptor with fsync(2), lseek(2) etc. (but not close(2)).
 399  *
 400  * @param channel       The dispatch I/O channel to schedule the barrier on.
 401  * @param context       The application-defined context parameter to pass to
 402  *                      the barrier function.
 403  * @param barrier       The barrier function.
 404  */
 405 API_AVAILABLE(macos(10.9), ios(7.0))
 406 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 407 void
 408 dispatch_io_barrier_f(dispatch_io_t channel,
 409         void *_Nullable context,
 410         dispatch_function_t barrier);
 411
 412 __END_DECLS
 413
 414 DISPATCH_ASSUME_NONNULL_END
 415
 416 #endif /* __DISPATCH_IO_PRIVATE__ */