dispatch_io_read(3)

💖 dispatch_io_read(3) — Library Functions Manual 💖

okay bestie, welcome to the group chat where we talk about dispatch_io_read and dispatch_io_write — the two functions that submit read and write operations to dispatch I/O channels. sit down, grab a strawberry 🍓, this one's actually fun.

---

✨ NAME ✨

dispatch_io_read, dispatch_io_write — submit read and write operations to dispatch I/O channels 🫶

---

✨ SYNOPSIS ✨

#include <dispatch/dispatch.h>

void
dispatch_io_read(dispatch_io_t channel, off_t offset, size_t length,
    dispatch_queue_t queue,
    void (^handler)(bool done, dispatch_data_t data, int error));

void
dispatch_io_write(dispatch_io_t channel, off_t offset,
    dispatch_data_t data, dispatch_queue_t queue,
    void (^handler)(bool done, dispatch_data_t data, int error));

---

✨ DESCRIPTION ✨

so the dispatch I/O framework is literally an API for asynchronous read and write I/O operations. it's giving... the ideas and idioms from the dispatch(3) framework, but applied to device I/O. the whole point? it lets an app more easily avoid blocking I/O operations, and it lets the app express its I/O requirements way more directly than by messing with the raw POSIX file API. and here's the slay part: dispatch I/O will make a best effort to optimize how and when asynchronous I/O operations get performed, based on the capabilities of the targeted device. no cap. 💅

this page is all about how to read from and write to dispatch I/O channels. creating and configuring those channels? that's a whole other conversation — go read dispatch_io_create(3). 🌸 the dispatch I/O framework also has the convenience functions dispatch_read(3) and dispatch_write(3) for the cases that don't need the full functionality that I/O channels give you.

---

✨ FUNDAMENTALS ✨

dispatch_io_read() and dispatch_io_write() are the functions you use to perform asynchronous read and write operations on dispatch I/O channels. think of them as the asynchronous versions of fread(3) and fwrite(3) from the standard C library. iconic behavior honestly. 👑

---

🌈 READ OPERATIONS 🌈

dispatch_io_read() schedules an I/O read operation on the specified dispatch I/O channel. as results from the read operation become available, the handler block you provided gets submitted to the specified queue. ✨ and that block gets passed a dispatch data object representing the data that has been read since the handler's previous invocation.

the offset parameter says where the read operation should begin. here's the nuance bestie, don't skip this:

• for a channel of DISPATCH_IO_RANDOM type, offset is interpreted relative to the position of the file pointer when the channel was created.
• for a channel of DISPATCH_IO_STREAM type, offset is ignored, and the read operation begins at the current file pointer position.

the length parameter says how many bytes should be read from the I/O channel. pass SIZE_MAX to just keep reading until EOF is encountered — and for a channel created from a disk-based file, that happens when reading past the end of the physical file. 💀

---

🌈 WRITE OPERATIONS 🌈

dispatch_io_write() schedules an I/O write operation on the specified dispatch I/O channel. as the write operation progresses, the handler block you provided gets submitted to the specified queue. and that block gets passed a dispatch data object representing the data that remains to be written as part of this I/O operation. 🦋

the offset parameter says where the write operation should begin. it's interpreted exactly as for read operations above, so scroll back up if you need it. 🙈

the data parameter specifies the location and amount of data to be written, all wrapped up as a dispatch data object. and heads up: the object is retained by the system until the write operation is complete. so don't be out here freeing things you shouldn't. ✋

---

🎀 I/O HANDLER BLOCKS 🎀

okay this section is the one people mess up, so pay attention bestie. 💜

dispatch I/O handler blocks submitted to a channel via dispatch_io_read() or dispatch_io_write() will be executed one or more times, depending on system load and the channel's configuration settings (details are in dispatch_io_create(3)). the handler block need not be reentrant safe — no new I/O handler instance gets submitted until the previously enqueued handler block has returned. so like, it's chill. 🌸

the dispatch data object passed to an I/O handler block will be released by the system when the block returns. so if you need access to the memory buffer it represents outside of the handler, the handler block must retain the data object, or create a new (e.g. concatenated) data object from it (see dispatch_data_create(3) for the deets). don't say I didn't warn you. 😭

once an I/O handler block is invoked with the done flag set, the associated I/O operation is complete and that handler block will not be run again. periodt. ✨ and if an unrecoverable error occurs while performing the I/O operation, the handler block gets submitted with the done flag set and the appropriate POSIX error code in the error parameter. and one more little vibe check for you: an invocation of a handler block with the done flag set, zero error, and data set to dispatch_data_empty means the I/O operation has encountered EOF. 👑

---

👑 SEE ALSO 👑

dispatch(3), dispatch_data_create(3), dispatch_io_create(3), dispatch_read(3), fread(3)

---

and that's the page, bestie!! 🫶 this one came to you from Darwin, dated December 1, 2010 — yeah, it's been serving since 2010 and it still ate. 💅✨ bye mwah 😘