Ch26.9: I/O Operations

中文(简体)

1. The Layer Below print, scan and transmit

The raw operations move characters or bytes and report how much moved. They do not format, parse or choose a buffer. They are what a device implementation is built on, and they are the escape hatch when a protocol needs exact control over one read, one write or one offset.

Application code normally uses print, scan and transmit. Those three handle formatting, buffered input lookahead and the zero-copy staging. The operations on this page are for the layer underneath, or for the rare case where the application really does need a raw byte window.

2. Read Operations

Operation Return Meaning
read_some(in, char* buf, count) std::size_t Read at most count characters. Returns how many were read; 0 means EOF.
read_all(in, char* buf, count) void Read exactly count characters or fail.
read_some_bytes(in, std::byte* buf, count) std::size_t The byte-addressed form; returns bytes read.
read_all_bytes(in, std::byte* buf, count) void Read exactly count bytes or fail.

char buf[4096];
auto const n{::fast_io::operations::read_some(in, buf, sizeof(buf))};
if (n == 0)
{
    // end of input
}

read_some is the primitive. It may return less than requested even when more data will arrive later. read_all is the convenience form that keeps reading until the requested count is satisfied.

3. Write Operations

Operation Return Meaning
write_some(out, char const* buf, count) std::size_t Write at most count characters; returns how many were accepted.
write_all(out, char const* buf, count) void Write every character or fail.
write_some_bytes(out, std::byte const* buf, count) std::size_t The byte-addressed form; returns bytes written.
write_all_bytes(out, std::byte const* buf, count) void Write every byte or fail.

A short write is normal on pipes and sockets. write_all loops until the whole buffer is accepted; write_some lets the caller decide what to do with the unsent suffix.

4. Positioned Operations

pread_* and pwrite_* take an explicit ::fast_io::intfpos_t offset. They do not consume the device's own position; this is the same distinction as POSIX pread/pwrite. Use them when several readers or writers share one file or when you are patching a record at a known offset.

Operation Return Meaning
pread_some(in, char* buf, count, off) std::size_t Read at off without advancing the stream position.
pread_all(in, char* buf, count, off) void Read exactly count characters at off.
pwrite_some(out, char const* buf, count, off) std::size_t Write at off without advancing the stream position.
pwrite_all(out, char const* buf, count, off) void Write every character at off.

The *_bytes forms take std::byte* and an offset in the same way. A pipe or socket is not seekable, so passing an offset there is a failure, not a silent fallback.

5. Scatter Operations

Scatter/gather operations take an array of ::fast_io::io_scatter_t entries instead of one contiguous buffer. Each entry is a base pointer plus a length. This avoids copying a set of buffers into one contiguous block just to write them.


::fast_io::io_scatter_t parts[2]{
    {header.data(), header.size()},
    {body.data(), body.size()}};

::fast_io::operations::scatter_write_all(out, parts, 2);
Family Forms
Read scatter_read_some, scatter_read_all, scatter_read_some_bytes, scatter_read_all_bytes
Write scatter_write_some, scatter_write_all, scatter_write_some_bytes, scatter_write_all_bytes
Positioned read scatter_pread_some, scatter_pread_all, scatter_pread_some_bytes, scatter_pread_all_bytes
Positioned write scatter_pwrite_some, scatter_pwrite_all, scatter_pwrite_some_bytes, scatter_pwrite_all_bytes

The *_some forms return io_scatter_status_t, which identifies the position in the scatter array and the position inside that entry. The *_all forms return void and fail if the whole scatter is not transferred.

6. Seek, Flush and Single Characters

Operation Meaning
io_stream_seek_bytes(stream, off, seekdir) Seek a bidirectional stream; returns the new position.
input_stream_seek_bytes, output_stream_seek_bytes Direction-specific seek. Header-side.
input_stream_buffer_flush, output_stream_buffer_flush, io_stream_buffer_flush Flush buffered data. Header-side.
char_put(out, ch) Write one character. Header-side.

seekdir is beg, cur or end. A buffered stream flushes or adjusts its buffer before the seek, so the position you get back is the one the device will use, not the stale buffer cursor.

7. Failure and Partial Progress

All of these operations report device failures as herbceptions. The difference between some and all is the partial-progress policy:

8. Module Export Boundary

The fast_io module exports the read, write, pread, pwrite and scatter families, plus io_stream_seek_bytes. The direction-specific seek forms, buffer-flush operations, char_put and some reference accessors are header-side today. Use #include <fast_io.h> for those.

Do not build application code here. Use print, scan and transmit unless you are implementing a device or a layer below fast_io. The raw operations move the buffer bookkeeping back into your code.

Key Takeaways