afb81b8278
Some checks failed
Docker. / Ubuntu (push) Has been cancelled
User-agent updater. / User-agent (push) Failing after 15s
Lock Threads / lock (push) Failing after 10s
Waiting for answer. / waiting-for-answer (push) Failing after 22s
Needs user action. / needs-user-action (push) Failing after 8s
Can't reproduce. / cant-reproduce (push) Failing after 8s
Close stale issues and PRs / stale (push) Has been cancelled
417 lines
18 KiB
C
417 lines
18 KiB
C
/*
|
|
* Copyright (c) 2009-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_IO_PRIVATE__
|
|
#define __DISPATCH_IO_PRIVATE__
|
|
|
|
#ifndef __DISPATCH_INDIRECT__
|
|
#error "Please #include <dispatch/dispatch.h> instead of this file directly."
|
|
#include <dispatch/base.h> // for HeaderDoc
|
|
#endif
|
|
|
|
DISPATCH_ASSUME_NONNULL_BEGIN
|
|
|
|
__BEGIN_DECLS
|
|
|
|
/*!
|
|
* @function dispatch_read_f
|
|
* Schedule a read operation for asynchronous execution on the specified file
|
|
* descriptor. The specified handler is enqueued with the data read from the
|
|
* file descriptor when the operation has completed or an error occurs.
|
|
*
|
|
* The data object passed to the handler will be automatically released by the
|
|
* system when the handler returns. It is the responsibility of the application
|
|
* to retain, concatenate or copy the data object if it is needed after the
|
|
* handler returns.
|
|
*
|
|
* The data object passed to the handler will only contain as much data as is
|
|
* currently available from the file descriptor (up to the specified length).
|
|
*
|
|
* If an unrecoverable error occurs on the file descriptor, the handler will be
|
|
* enqueued with the appropriate error code along with a data object of any data
|
|
* that could be read successfully.
|
|
*
|
|
* An invocation of the handler with an error code of zero and an empty data
|
|
* object indicates that EOF was reached.
|
|
*
|
|
* The system takes control of the file descriptor until the handler is
|
|
* enqueued, and during this time file descriptor flags such as O_NONBLOCK will
|
|
* be modified by the system on behalf of the application. It is an error for
|
|
* the application to modify a file descriptor directly while it is under the
|
|
* control of the system, but it may create additional dispatch I/O convenience
|
|
* operations or dispatch I/O channels associated with that file descriptor.
|
|
*
|
|
* @param fd The file descriptor from which to read the data.
|
|
* @param length The length of data to read from the file descriptor,
|
|
* or SIZE_MAX to indicate that all of the data currently
|
|
* available from the file descriptor should be read.
|
|
* @param queue The dispatch queue to which the handler should be
|
|
* submitted.
|
|
* @param context The application-defined context parameter to pass to
|
|
* the handler function.
|
|
* @param handler The handler to enqueue when data is ready to be
|
|
* delivered.
|
|
* param context Application-defined context parameter.
|
|
* param data The data read from the file descriptor.
|
|
* param error An errno condition for the read operation or
|
|
* zero if the read was successful.
|
|
*/
|
|
API_AVAILABLE(macos(10.9), ios(7.0))
|
|
DISPATCH_EXPORT DISPATCH_NONNULL3 DISPATCH_NONNULL5 DISPATCH_NOTHROW
|
|
void
|
|
dispatch_read_f(dispatch_fd_t fd,
|
|
size_t length,
|
|
dispatch_queue_t queue,
|
|
void *_Nullable context,
|
|
void (*handler)(void *_Nullable context, dispatch_data_t data, int error));
|
|
|
|
/*!
|
|
* @function dispatch_write_f
|
|
* Schedule a write operation for asynchronous execution on the specified file
|
|
* descriptor. The specified handler is enqueued when the operation has
|
|
* completed or an error occurs.
|
|
*
|
|
* If an unrecoverable error occurs on the file descriptor, the handler will be
|
|
* enqueued with the appropriate error code along with the data that could not
|
|
* be successfully written.
|
|
*
|
|
* An invocation of the handler with an error code of zero indicates that the
|
|
* data was fully written to the channel.
|
|
*
|
|
* The system takes control of the file descriptor until the handler is
|
|
* enqueued, and during this time file descriptor flags such as O_NONBLOCK will
|
|
* be modified by the system on behalf of the application. It is an error for
|
|
* the application to modify a file descriptor directly while it is under the
|
|
* control of the system, but it may create additional dispatch I/O convenience
|
|
* operations or dispatch I/O channels associated with that file descriptor.
|
|
*
|
|
* @param fd The file descriptor to which to write the data.
|
|
* @param data The data object to write to the file descriptor.
|
|
* @param queue The dispatch queue to which the handler should be
|
|
* submitted.
|
|
* @param context The application-defined context parameter to pass to
|
|
* the handler function.
|
|
* @param handler The handler to enqueue when the data has been written.
|
|
* param context Application-defined context parameter.
|
|
* param data The data that could not be written to the I/O
|
|
* channel, or NULL.
|
|
* param error An errno condition for the write operation or
|
|
* zero if the write was successful.
|
|
*/
|
|
API_AVAILABLE(macos(10.9), ios(7.0))
|
|
DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NONNULL3 DISPATCH_NONNULL5
|
|
DISPATCH_NOTHROW
|
|
void
|
|
dispatch_write_f(dispatch_fd_t fd,
|
|
dispatch_data_t data,
|
|
dispatch_queue_t queue,
|
|
void *_Nullable context,
|
|
void (*handler)(void *_Nullable context, dispatch_data_t _Nullable data,
|
|
int error));
|
|
|
|
/*!
|
|
* @function dispatch_io_create_f
|
|
* Create a dispatch I/O channel associated with a file descriptor. The system
|
|
* takes control of the file descriptor until the channel is closed, an error
|
|
* occurs on the file descriptor or all references to the channel are released.
|
|
* At that time the specified cleanup handler will be enqueued and control over
|
|
* the file descriptor relinquished.
|
|
*
|
|
* While a file descriptor is under the control of a dispatch I/O channel, file
|
|
* descriptor flags such as O_NONBLOCK will be modified by the system on behalf
|
|
* of the application. It is an error for the application to modify a file
|
|
* descriptor directly while it is under the control of a dispatch I/O channel,
|
|
* but it may create additional channels associated with that file descriptor.
|
|
*
|
|
* @param type The desired type of I/O channel (DISPATCH_IO_STREAM
|
|
* or DISPATCH_IO_RANDOM).
|
|
* @param fd The file descriptor to associate with the I/O channel.
|
|
* @param queue The dispatch queue to which the handler should be submitted.
|
|
* @param context The application-defined context parameter to pass to
|
|
* the cleanup handler function.
|
|
* @param cleanup_handler The handler to enqueue when the system
|
|
* relinquishes control over the file descriptor.
|
|
* param context Application-defined context parameter.
|
|
* param error An errno condition if control is relinquished
|
|
* because channel creation failed, zero otherwise.
|
|
* @result The newly created dispatch I/O channel or NULL if an error
|
|
* occurred (invalid type specified).
|
|
*/
|
|
API_AVAILABLE(macos(10.9), ios(7.0))
|
|
DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
|
|
DISPATCH_NOTHROW
|
|
dispatch_io_t
|
|
dispatch_io_create_f(dispatch_io_type_t type,
|
|
dispatch_fd_t fd,
|
|
dispatch_queue_t queue,
|
|
void *_Nullable context,
|
|
void (*cleanup_handler)(void *_Nullable context, int error));
|
|
|
|
/*!
|
|
* @function dispatch_io_create_with_path_f
|
|
* Create a dispatch I/O channel associated with a path name. The specified
|
|
* path, oflag and mode parameters will be passed to open(2) when the first I/O
|
|
* operation on the channel is ready to execute and the resulting file
|
|
* descriptor will remain open and under the control of the system until the
|
|
* channel is closed, an error occurs on the file descriptor or all references
|
|
* to the channel are released. At that time the file descriptor will be closed
|
|
* and the specified cleanup handler will be enqueued.
|
|
*
|
|
* @param type The desired type of I/O channel (DISPATCH_IO_STREAM
|
|
* or DISPATCH_IO_RANDOM).
|
|
* @param path The absolute path to associate with the I/O channel.
|
|
* @param oflag The flags to pass to open(2) when opening the file at
|
|
* path.
|
|
* @param mode The mode to pass to open(2) when creating the file at
|
|
* path (i.e. with flag O_CREAT), zero otherwise.
|
|
* @param queue The dispatch queue to which the handler should be
|
|
* submitted.
|
|
* @param context The application-defined context parameter to pass to
|
|
* the cleanup handler function.
|
|
* @param cleanup_handler The handler to enqueue when the system
|
|
* has closed the file at path.
|
|
* param context Application-defined context parameter.
|
|
* param error An errno condition if control is relinquished
|
|
* because channel creation or opening of the
|
|
* specified file failed, zero otherwise.
|
|
* @result The newly created dispatch I/O channel or NULL if an error
|
|
* occurred (invalid type or non-absolute path specified).
|
|
*/
|
|
API_AVAILABLE(macos(10.9), ios(7.0))
|
|
DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED
|
|
DISPATCH_WARN_RESULT DISPATCH_NOTHROW
|
|
dispatch_io_t
|
|
dispatch_io_create_with_path_f(dispatch_io_type_t type,
|
|
const char *path, int oflag, mode_t mode,
|
|
dispatch_queue_t queue,
|
|
void *_Nullable context,
|
|
void (*cleanup_handler)(void *_Nullable context, int error));
|
|
|
|
/*!
|
|
* @function dispatch_io_create_with_io_f
|
|
* Create a new dispatch I/O channel from an existing dispatch I/O channel.
|
|
* The new channel inherits the file descriptor or path name associated with
|
|
* the existing channel, but not its channel type or policies.
|
|
*
|
|
* If the existing channel is associated with a file descriptor, control by the
|
|
* system over that file descriptor is extended until the new channel is also
|
|
* closed, an error occurs on the file descriptor, or all references to both
|
|
* channels are released. At that time the specified cleanup handler will be
|
|
* enqueued and control over the file descriptor relinquished.
|
|
*
|
|
* While a file descriptor is under the control of a dispatch I/O channel, file
|
|
* descriptor flags such as O_NONBLOCK will be modified by the system on behalf
|
|
* of the application. It is an error for the application to modify a file
|
|
* descriptor directly while it is under the control of a dispatch I/O channel,
|
|
* but it may create additional channels associated with that file descriptor.
|
|
*
|
|
* @param type The desired type of I/O channel (DISPATCH_IO_STREAM
|
|
* or DISPATCH_IO_RANDOM).
|
|
* @param io The existing channel to create the new I/O channel from.
|
|
* @param queue The dispatch queue to which the handler should be submitted.
|
|
* @param context The application-defined context parameter to pass to
|
|
* the cleanup handler function.
|
|
* @param cleanup_handler The handler to enqueue when the system
|
|
* relinquishes control over the file descriptor
|
|
* (resp. closes the file at path) associated with
|
|
* the existing channel.
|
|
* param context Application-defined context parameter.
|
|
* param error An errno condition if control is relinquished
|
|
* because channel creation failed, zero otherwise.
|
|
* @result The newly created dispatch I/O channel or NULL if an error
|
|
* occurred (invalid type specified).
|
|
*/
|
|
API_AVAILABLE(macos(10.9), ios(7.0))
|
|
DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED
|
|
DISPATCH_WARN_RESULT DISPATCH_NOTHROW
|
|
dispatch_io_t
|
|
dispatch_io_create_with_io_f(dispatch_io_type_t type,
|
|
dispatch_io_t io,
|
|
dispatch_queue_t queue,
|
|
void *_Nullable context,
|
|
void (*cleanup_handler)(void *_Nullable context, int error));
|
|
|
|
/*!
|
|
* @typedef dispatch_io_handler_function_t
|
|
* The prototype of I/O handler functions for dispatch I/O operations.
|
|
*
|
|
* @param context Application-defined context parameter.
|
|
* @param done A flag indicating whether the operation is complete.
|
|
* @param data The data object to be handled.
|
|
* @param error An errno condition for the operation.
|
|
*/
|
|
typedef void (*dispatch_io_handler_function_t)(void *_Nullable context,
|
|
bool done, dispatch_data_t _Nullable data, int error);
|
|
|
|
/*!
|
|
* @function dispatch_io_read_f
|
|
* Schedule a read operation for asynchronous execution on the specified I/O
|
|
* channel. The I/O handler is enqueued one or more times depending on the
|
|
* general load of the system and the policy specified on the I/O channel.
|
|
*
|
|
* Any data read from the channel is described by the dispatch data object
|
|
* passed to the I/O handler. This object will be automatically released by the
|
|
* system when the I/O handler returns. It is the responsibility of the
|
|
* application to retain, concatenate or copy the data object if it is needed
|
|
* after the I/O handler returns.
|
|
*
|
|
* Dispatch I/O handlers are not reentrant. The system will ensure that no new
|
|
* I/O handler instance is invoked until the previously enqueued handler
|
|
* function has returned.
|
|
*
|
|
* An invocation of the I/O handler with the done flag set indicates that the
|
|
* read operation is complete and that the handler will not be enqueued again.
|
|
*
|
|
* If an unrecoverable error occurs on the I/O channel's underlying file
|
|
* descriptor, the I/O handler will be enqueued with the done flag set, the
|
|
* appropriate error code and a NULL data object.
|
|
*
|
|
* An invocation of the I/O handler with the done flag set, an error code of
|
|
* zero and an empty data object indicates that EOF was reached.
|
|
*
|
|
* @param channel The dispatch I/O channel from which to read the data.
|
|
* @param offset The offset relative to the channel position from which
|
|
* to start reading (only for DISPATCH_IO_RANDOM).
|
|
* @param length The length of data to read from the I/O channel, or
|
|
* SIZE_MAX to indicate that data should be read until EOF
|
|
* is reached.
|
|
* @param queue The dispatch queue to which the I/O handler should be
|
|
* submitted.
|
|
* @param context The application-defined context parameter to pass to
|
|
* the handler function.
|
|
* @param io_handler The I/O handler to enqueue when data is ready to be
|
|
* delivered.
|
|
* param context Application-defined context parameter.
|
|
* param done A flag indicating whether the operation is complete.
|
|
* param data An object with the data most recently read from the
|
|
* I/O channel as part of this read operation, or NULL.
|
|
* param error An errno condition for the read operation or zero if
|
|
* the read was successful.
|
|
*/
|
|
API_AVAILABLE(macos(10.9), ios(7.0))
|
|
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL4 DISPATCH_NONNULL6
|
|
DISPATCH_NOTHROW
|
|
void
|
|
dispatch_io_read_f(dispatch_io_t channel,
|
|
off_t offset,
|
|
size_t length,
|
|
dispatch_queue_t queue,
|
|
void *_Nullable context,
|
|
dispatch_io_handler_function_t io_handler);
|
|
|
|
/*!
|
|
* @function dispatch_io_write_f
|
|
* Schedule a write operation for asynchronous execution on the specified I/O
|
|
* channel. The I/O handler is enqueued one or more times depending on the
|
|
* general load of the system and the policy specified on the I/O channel.
|
|
*
|
|
* Any data remaining to be written to the I/O channel is described by the
|
|
* dispatch data object passed to the I/O handler. This object will be
|
|
* automatically released by the system when the I/O handler returns. It is the
|
|
* responsibility of the application to retain, concatenate or copy the data
|
|
* object if it is needed after the I/O handler returns.
|
|
*
|
|
* Dispatch I/O handlers are not reentrant. The system will ensure that no new
|
|
* I/O handler instance is invoked until the previously enqueued handler
|
|
* function has returned.
|
|
*
|
|
* An invocation of the I/O handler with the done flag set indicates that the
|
|
* write operation is complete and that the handler will not be enqueued again.
|
|
*
|
|
* If an unrecoverable error occurs on the I/O channel's underlying file
|
|
* descriptor, the I/O handler will be enqueued with the done flag set, the
|
|
* appropriate error code and an object containing the data that could not be
|
|
* written.
|
|
*
|
|
* An invocation of the I/O handler with the done flag set and an error code of
|
|
* zero indicates that the data was fully written to the channel.
|
|
*
|
|
* @param channel The dispatch I/O channel on which to write the data.
|
|
* @param offset The offset relative to the channel position from which
|
|
* to start writing (only for DISPATCH_IO_RANDOM).
|
|
* @param data The data to write to the I/O channel. The data object
|
|
* will be retained by the system until the write operation
|
|
* is complete.
|
|
* @param queue The dispatch queue to which the I/O handler should be
|
|
* submitted.
|
|
* @param context The application-defined context parameter to pass to
|
|
* the handler function.
|
|
* @param io_handler The I/O handler to enqueue when data has been delivered.
|
|
* param context Application-defined context parameter.
|
|
* param done A flag indicating whether the operation is complete.
|
|
* param data An object of the data remaining to be
|
|
* written to the I/O channel as part of this write
|
|
* operation, or NULL.
|
|
* param error An errno condition for the write operation or zero
|
|
* if the write was successful.
|
|
*/
|
|
API_AVAILABLE(macos(10.9), ios(7.0))
|
|
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NONNULL4
|
|
DISPATCH_NONNULL6 DISPATCH_NOTHROW
|
|
void
|
|
dispatch_io_write_f(dispatch_io_t channel,
|
|
off_t offset,
|
|
dispatch_data_t data,
|
|
dispatch_queue_t queue,
|
|
void *_Nullable context,
|
|
dispatch_io_handler_function_t io_handler);
|
|
|
|
/*!
|
|
* @function dispatch_io_barrier_f
|
|
* Schedule a barrier operation on the specified I/O channel; all previously
|
|
* scheduled operations on the channel will complete before the provided
|
|
* barrier function is enqueued onto the global queue determined by the
|
|
* channel's target queue, and no subsequently scheduled operations will start
|
|
* until the barrier function has returned.
|
|
*
|
|
* If multiple channels are associated with the same file descriptor, a barrier
|
|
* operation scheduled on any of these channels will act as a barrier across all
|
|
* channels in question, i.e. all previously scheduled operations on any of the
|
|
* channels will complete before the barrier function is enqueued, and no
|
|
* operations subsequently scheduled on any of the channels will start until the
|
|
* barrier function has returned.
|
|
*
|
|
* While the barrier function is running, it may safely operate on the channel's
|
|
* underlying file descriptor with fsync(2), lseek(2) etc. (but not close(2)).
|
|
*
|
|
* @param channel The dispatch I/O channel to schedule the barrier on.
|
|
* @param context The application-defined context parameter to pass to
|
|
* the barrier function.
|
|
* @param barrier The barrier function.
|
|
*/
|
|
API_AVAILABLE(macos(10.9), ios(7.0))
|
|
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
|
|
void
|
|
dispatch_io_barrier_f(dispatch_io_t channel,
|
|
void *_Nullable context,
|
|
dispatch_function_t barrier);
|
|
|
|
__END_DECLS
|
|
|
|
DISPATCH_ASSUME_NONNULL_END
|
|
|
|
#endif /* __DISPATCH_IO_PRIVATE__ */
|