[apple/libdispatch.git] / man / dispatch_io_read.3

.\" Copyright (c) 2010 Apple Inc. All rights reserved.
.Dd December 1, 2010
.Dt dispatch_io_read 3
.Os Darwin
.Sh NAME
.Nm dispatch_io_read ,
.Nm dispatch_io_write
.Nd submit read and write operations to dispatch I/O channels
.Sh SYNOPSIS
.Fd #include <dispatch/dispatch.h>
.Ft void
.Fo dispatch_io_read
.Fa "dispatch_io_t channel"
.Fa "off_t offset"
.Fa "size_t length"
.Fa "dispatch_queue_t queue"
.Fa "void (^handler)(bool done, dispatch_data_t data, int error)"
.Fc
.Ft void
.Fo dispatch_io_write
.Fa "dispatch_io_t channel"
.Fa "off_t offset"
.Fa "dispatch_data_t dispatch"
.Fa "dispatch_queue_t queue"
.Fa "void (^handler)(bool done, dispatch_data_t data, int error)"
.Fc
.Sh DESCRIPTION
The dispatch I/O framework is an API for asynchronous read and write I/O
operations. It is an application of the ideas and idioms present in the
.Xr dispatch 3
framework to device I/O. Dispatch I/O enables an application to more easily
avoid blocking I/O operations and allows it to more directly express its I/O
requirements than by using the raw POSIX file API. Dispatch I/O will make a
best effort to optimize how and when asynchronous I/O operations are performed
based on the capabilities of the targeted device.
.Pp
This page provides details on how to read from and write to dispatch I/O
channels. Creation and configuration of these channels is covered in the
.Xr dispatch_io_create 3
page. The dispatch I/O framework also provides the convenience functions
.Xr dispatch_read 3
and
.Xr dispatch_write 3
for uses that do not require the full functionality provided by I/O channels.
.Pp
.Sh FUNDAMENTALS
The
.Fn dispatch_io_read
and
.Fn dispatch_io_write
functions are used to perform asynchronous read and write operations on
dispatch I/O channels. They can be thought of as asynchronous versions of the
.Xr fread 3
and
.Xr fwrite 3
functions in the standard C library.
.Sh READ OPERATIONS
The
.Fn dispatch_io_read
function schedules an I/O read operation on the specified dispatch I/O
.Va channel .
As results from the read operation become available, the provided
.Va handler
block will be submitted to the specified
.Va queue .
The block will be passed a dispatch data object representing the data that has
been read since the handler's previous invocation.
.Pp
The
.Va offset
parameter indicates where the read operation should begin. For a channel of
.Dv DISPATCH_IO_RANDOM
type it is interpreted relative to the position of the file pointer when the
channel was created, for a channel of
.Dv DISPATCH_IO_STREAM
type it is ignored and the read operation will begin at the current file
pointer position.
.Pp
The
.Va length
parameter indicates the number of bytes that should be read from the I/O
channel. Pass
.Dv SIZE_MAX
to keep reading until EOF is encountered (for a channel created from a
disk-based file this happens when reading past the end of the physical file).
.Sh WRITE OPERATIONS
The
.Fn dispatch_io_write
function schedules an I/O write operation on the specified dispatch I/O
.Va channel .
As the write operation progresses, the provided
.Va handler
block will be submitted to the specified
.Va queue .
The block will be passed a dispatch data object representing the data that
remains to be written as part of this I/O operation.
.Pp
The
.Va offset
parameter indicates where the write operation should begin. It is interpreted
as for read operations above.
.Pp
The
.Va data
parameter specifies the location and amount of data to be written, encapsulated
as a dispatch data object. The object is retained by the system until the write
operation is complete.
.Sh I/O HANDLER BLOCKS
Dispatch I/O handler blocks submitted to a channel via the
.Fn dispatch_io_read
or
.Fn dispatch_io_write
functions will be executed one or more times depending on system load and the
channel's configuration settings (see
.Xr dispatch_io_create 3
for details). The handler block need not be reentrant safe,
no new I/O handler instance is submitted until the previously enqueued handler
block has returned.
.Pp
The dispatch
.Va data
object passed to an I/O handler block will be released by the system when the
block returns, if access to the memory buffer it represents is needed outside
of the handler, the handler block must retain the data object or create a new
(e.g.\& concatenated) data object from it (see
.Xr dispatch_data_create 3
for details).
.Pp
Once an I/O handler block is invoked with the
.Va done
flag set, the associated I/O operation is complete and that handler block will
not be run again. If an unrecoverable error occurs while performing the I/O
operation, the handler block will be submitted with the
.Va done
flag set and the appriate POSIX error code in the
.Va error
parameter. An invocation of a handler block with the
.Va done
flag set, zero
.Va error
and
.Va data
set to
.Vt dispatch_data_empty
indicates that the I/O operation has encountered EOF.
.Sh SEE ALSO
.Xr dispatch 3 ,
.Xr dispatch_data_create 3 ,
.Xr dispatch_io_create 3 ,
.Xr dispatch_read 3 ,
.Xr fread 3
Commit	Line	Data
e85f4437 A	1	.\" Copyright (c) 2010 Apple Inc. All rights reserved.
	2	.Dd December 1, 2010
	3	.Dt dispatch_io_read 3
	4	.Os Darwin
	5	.Sh NAME
	6	.Nm dispatch_io_read ,
	7	.Nm dispatch_io_write
	8	.Nd submit read and write operations to dispatch I/O channels
	9	.Sh SYNOPSIS
	10	.Fd #include <dispatch/dispatch.h>
	11	.Ft void
	12	.Fo dispatch_io_read
	13	.Fa "dispatch_io_t channel"
	14	.Fa "off_t offset"
	15	.Fa "size_t length"
	16	.Fa "dispatch_queue_t queue"
	17	.Fa "void (^handler)(bool done, dispatch_data_t data, int error)"
	18	.Fc
	19	.Ft void
	20	.Fo dispatch_io_write
	21	.Fa "dispatch_io_t channel"
	22	.Fa "off_t offset"
	23	.Fa "dispatch_data_t dispatch"
	24	.Fa "dispatch_queue_t queue"
	25	.Fa "void (^handler)(bool done, dispatch_data_t data, int error)"
	26	.Fc
	27	.Sh DESCRIPTION
	28	The dispatch I/O framework is an API for asynchronous read and write I/O
	29	operations. It is an application of the ideas and idioms present in the
	30	.Xr dispatch 3
	31	framework to device I/O. Dispatch I/O enables an application to more easily
	32	avoid blocking I/O operations and allows it to more directly express its I/O
	33	requirements than by using the raw POSIX file API. Dispatch I/O will make a
	34	best effort to optimize how and when asynchronous I/O operations are performed
	35	based on the capabilities of the targeted device.
	36	.Pp
	37	This page provides details on how to read from and write to dispatch I/O
	38	channels. Creation and configuration of these channels is covered in the
	39	.Xr dispatch_io_create 3
	40	page. The dispatch I/O framework also provides the convenience functions
	41	.Xr dispatch_read 3
	42	and
	43	.Xr dispatch_write 3
	44	for uses that do not require the full functionality provided by I/O channels.
	45	.Pp
	46	.Sh FUNDAMENTALS
	47	The
	48	.Fn dispatch_io_read
	49	and
	50	.Fn dispatch_io_write
	51	functions are used to perform asynchronous read and write operations on
	52	dispatch I/O channels. They can be thought of as asynchronous versions of the
	53	.Xr fread 3
	54	and
	55	.Xr fwrite 3
	56	functions in the standard C library.
	57	.Sh READ OPERATIONS
	58	The
	59	.Fn dispatch_io_read
	60	function schedules an I/O read operation on the specified dispatch I/O
	61	.Va channel .
	62	As results from the read operation become available, the provided
	63	.Va handler
	64	block will be submitted to the specified
65	.Va queue .
66	The block will be passed a dispatch data object representing the data that has
67	been read since the handler's previous invocation.
68	.Pp
69	The
70	.Va offset
71	parameter indicates where the read operation should begin. For a channel of
72	.Dv DISPATCH_IO_RANDOM
73	type it is interpreted relative to the position of the file pointer when the
74	channel was created, for a channel of
75	.Dv DISPATCH_IO_STREAM
76	type it is ignored and the read operation will begin at the current file
77	pointer position.
78	.Pp
79	The
80	.Va length
81	parameter indicates the number of bytes that should be read from the I/O
82	channel. Pass
83	.Dv SIZE_MAX
84	to keep reading until EOF is encountered (for a channel created from a
85	disk-based file this happens when reading past the end of the physical file).
86	.Sh WRITE OPERATIONS
87	The
88	.Fn dispatch_io_write
89	function schedules an I/O write operation on the specified dispatch I/O
90	.Va channel .
91	As the write operation progresses, the provided
92	.Va handler
93	block will be submitted to the specified
94	.Va queue .
95	The block will be passed a dispatch data object representing the data that
96	remains to be written as part of this I/O operation.
97	.Pp
98	The
99	.Va offset
100	parameter indicates where the write operation should begin. It is interpreted
101	as for read operations above.
102	.Pp
103	The
104	.Va data
105	parameter specifies the location and amount of data to be written, encapsulated
106	as a dispatch data object. The object is retained by the system until the write
107	operation is complete.
108	.Sh I/O HANDLER BLOCKS
109	Dispatch I/O handler blocks submitted to a channel via the
110	.Fn dispatch_io_read
111	or
112	.Fn dispatch_io_write
113	functions will be executed one or more times depending on system load and the
114	channel's configuration settings (see
115	.Xr dispatch_io_create 3
116	for details). The handler block need not be reentrant safe,
117	no new I/O handler instance is submitted until the previously enqueued handler
118	block has returned.
119	.Pp
120	The dispatch
121	.Va data
122	object passed to an I/O handler block will be released by the system when the
123	block returns, if access to the memory buffer it represents is needed outside
124	of the handler, the handler block must retain the data object or create a new
125	(e.g.\& concatenated) data object from it (see
126	.Xr dispatch_data_create 3
127	for details).
128	.Pp
129	Once an I/O handler block is invoked with the
130	.Va done
131	flag set, the associated I/O operation is complete and that handler block will
132	not be run again. If an unrecoverable error occurs while performing the I/O
133	operation, the handler block will be submitted with the
134	.Va done
135	flag set and the appriate POSIX error code in the
136	.Va error
137	parameter. An invocation of a handler block with the
138	.Va done
139	flag set, zero
140	.Va error
141	and
142	.Va data
143	set to
144	.Vt dispatch_data_empty
145	indicates that the I/O operation has encountered EOF.
146	.Sh SEE ALSO
147	.Xr dispatch 3 ,
148	.Xr dispatch_data_create 3 ,
149	.Xr dispatch_io_create 3 ,
150	.Xr dispatch_read 3 ,
151	.Xr fread 3