dispatch_io_read(3)

1dispatch_io_read(3)      BSD Library Functions Manual      dispatch_io_read(3)
2

NAME

4     dispatch_io_read, dispatch_io_write — submit read and write operations to
5     dispatch I/O channels
6

SYNOPSIS

8     #include <dispatch/dispatch.h>
9
10     void
11     dispatch_io_read(dispatch_io_t channel, off_t offset, size_t length,
12         dispatch_queue_t queue,
13         void (^handler)(bool done, dispatch_data_t data, int error));
14
15     void
16     dispatch_io_write(dispatch_io_t channel, off_t offset,
17         dispatch_data_t data, dispatch_queue_t queue,
18         void (^handler)(bool done, dispatch_data_t data, int error));
19

DESCRIPTION

21     The dispatch I/O framework is an API for asynchronous read and write I/O
22     operations. It is an application of the ideas and idioms present in the
23     dispatch(3) framework to device I/O. Dispatch I/O enables an application
24     to more easily avoid blocking I/O operations and allows it to more
25     directly express its I/O requirements than by using the raw POSIX file
26     API. Dispatch I/O will make a best effort to optimize how and when asyn‐
27     chronous I/O operations are performed based on the capabilities of the
28     targeted device.
29
30     This page provides details on how to read from and write to dispatch I/O
31     channels. Creation and configuration of these channels is covered in the
32     dispatch_io_create(3) page. The dispatch I/O framework also provides the
33     convenience functions dispatch_read(3) and dispatch_write(3) for uses
34     that do not require the full functionality provided by I/O channels.
35

FUNDAMENTALS

37     The dispatch_io_read() and dispatch_io_write() functions are used to per‐
38     form asynchronous read and write operations on dispatch I/O channels.
39     They can be thought of as asynchronous versions of the fread(3) and
40     fwrite(3) functions in the standard C library.
41

READ OPERATIONS

43     The dispatch_io_read() function schedules an I/O read operation on the
44     specified dispatch I/O channel.  As results from the read operation
45     become available, the provided handler block will be submitted to the
46     specified queue.  The block will be passed a dispatch data object repre‐
47     senting the data that has been read since the handler's previous invoca‐
48     tion.
49
50     The offset parameter indicates where the read operation should begin. For
51     a channel of DISPATCH_IO_RANDOM type it is interpreted relative to the
52     position of the file pointer when the channel was created, for a channel
53     of DISPATCH_IO_STREAM type it is ignored and the read operation will
54     begin at the current file pointer position.
55
56     The length parameter indicates the number of bytes that should be read
57     from the I/O channel. Pass SIZE_MAX to keep reading until EOF is encoun‐
58     tered (for a channel created from a disk-based file this happens when
59     reading past the end of the physical file).
60

WRITE OPERATIONS

62     The dispatch_io_write() function schedules an I/O write operation on the
63     specified dispatch I/O channel.  As the write operation progresses, the
64     provided handler block will be submitted to the specified queue.  The
65     block will be passed a dispatch data object representing the data that
66     remains to be written as part of this I/O operation.
67
68     The offset parameter indicates where the write operation should begin. It
69     is interpreted as for read operations above.
70
71     The data parameter specifies the location and amount of data to be writ‐
72     ten, encapsulated as a dispatch data object. The object is retained by
73     the system until the write operation is complete.
74

I/O HANDLER BLOCKS

76     Dispatch I/O handler blocks submitted to a channel via the
77     dispatch_io_read() or dispatch_io_write() functions will be executed one
78     or more times depending on system load and the channel's configuration
79     settings (see dispatch_io_create(3) for details). The handler block need
80     not be reentrant safe, no new I/O handler instance is submitted until the
81     previously enqueued handler block has returned.
82
83     The dispatch data object passed to an I/O handler block will be released
84     by the system when the block returns, if access to the memory buffer it
85     represents is needed outside of the handler, the handler block must
86     retain the data object or create a new (e.g. concatenated) data object
87     from it (see dispatch_data_create(3) for details).
88
89     Once an I/O handler block is invoked with the done flag set, the associ‐
90     ated I/O operation is complete and that handler block will not be run
91     again. If an unrecoverable error occurs while performing the I/O opera‐
92     tion, the handler block will be submitted with the done flag set and the
93     appropriate POSIX error code in the error parameter. An invocation of a
94     handler block with the done flag set, zero error and data set to
95     dispatch_data_empty indicates that the I/O operation has encountered EOF.
96