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