Module io 

IO: Handle (async operations on std’s sockets and files), the futures-io traits, and the utilities every stream gets: the reads and writes of AsyncReadExt, AsyncWriteExt, AsyncBufReadExt and AsyncSeekExt as futures, ReadBuf, copy and copy_bidirectional, BufReader, BufWriter and BufStream, the in-memory pipes duplex and simplex, split, empty, repeat and sink, the process’s stdin, stdout and stderr, what the sockets’ readiness calls take and answer (Interest, Ready), the caller’s own buffers the owned calls take and give back (IoBuf, IoBufMut, IoVecBuf, IoVecBufMut, AlignedBuf), and on unix AsyncFd, a caller’s own descriptor driven by readiness.

Inside, the shards’ half of IO: sources, the drivers’ half of every handle, and the system calls they make. A handle’s IO object stays its own (std’s sockets and files); its source is what the shard’s driver reaches. The driver completes every operation, into and out of the pool’s buffers, at once when it can and on readiness otherwise, and wakes the task, which takes the result.

Modules

unix

Unix’s own: AsyncFd, a caller’s descriptor driven by readiness, and its guards.

Structs

AlignedBuf

A buffer of a fixed capacity whose memory starts at an address that is a multiple of a chosen alignment: the buffer a file opened for direct IO (O_DIRECT, FILE_FLAG_NO_BUFFERING) is read into and written from by the owned calls (Handle::read_at_owned, Handle::write_at_owned and the others), which hand its memory to the kernel as it is.

BufReader

A reader with a buffer in front: small reads take from the buffer, which is filled by large reads of the reader. Writes, if the reader is also a writer, go straight through.

BufStream

A stream with a read buffer and a write buffer in front: a BufReader around a BufWriter.

BufWriter

A writer with a buffer in front: small writes gather in the buffer, which goes to the writer when full, on a flush, or on a close. Reads, if the writer is also a reader, go straight through. Dropping it loses what is still buffered: flush or close it first.

Chain

A reader that reads one to its end, then another; made by chain.

DuplexStream

One end of a duplex pair: what it writes the other reads, and what the other writes it reads. Dropping it ends the other’s reads (after what is left) and fails the other’s writes.

Empty

A reader at its end at once, and a writer that takes every byte and keeps none. Made by empty.

FillBuf

The future of fill_buf.

Flush

The future of flush.

Handle

An IO object (a socket, a pipe, a file) whose operations run on nuclei’s shards.

Interest

What a readiness call waits for: reading, writing, or either.

Lines

The lines of a buffered reader; made by lines.

Read

The future of read.

ReadBuf

A buffer being filled by reads: its first filled bytes hold data, its first initialized bytes are initialized (filled <= initialized), and the rest may be uninitialized memory that a read may write into.

ReadBufFuture

The future of read_buf.

ReadExact

The future of read_exact.

ReadHalf

The read half of a stream split in two.

ReadLine

The future of read_line.

ReadNumber

The future of a typed read (read_u32 and the like).

ReadToEnd

The future of read_to_end.

ReadToString

The future of read_to_string.

ReadUntil

The future of read_until.

Ready

What a readiness call found.

Repeat

A reader that gives one byte over and over, without end. Made by repeat.

Seek

The future of seek and the seeks built on it.

Shutdown

The future of shutdown.

SimplexReader

The reading end of a simplex pipe. Dropping it fails the writer’s next write.

SimplexWriter

The writing end of a simplex pipe. Dropping it (or closing it) ends the reader’s reads after what is left.

Sink

A writer that takes every byte and keeps none. Made by sink.

Split

The segments of a buffered reader between a byte; made by split.

Stderr

The process’s standard error: writes run on the blocking pool, one at a time.

Stdin

The process’s standard input: reads run on the blocking pool.

Stdout

The process’s standard output: writes run on the blocking pool, one at a time; flush before the process exits to see the last one done.

Take

A reader that ends after a number of bytes of another; made by take.

Write

The future of write.

WriteAll

The future of write_all.

WriteHalf

The write half of a stream split in two.

WriteNumber

The future of a typed write (write_u32 and the like).

WriteVectored

The future of write_vectored.

Traits

AsyncBufRead

Read bytes asynchronously.

AsyncBufReadExt

Reads on any AsyncBufRead: up to a delimiter, a line, the lines or the segments one by one.

AsyncRead

Read bytes asynchronously.

AsyncReadExt

Reads on any AsyncRead: into a slice, a ReadBuf, to the end, as typed numbers in big or little endian.

AsyncSeek

Seek bytes asynchronously.

AsyncSeekExt

Seeks on any AsyncSeek.

AsyncWrite

Write bytes asynchronously.

AsyncWriteExt

Writes on any AsyncWrite: a slice, all of a slice, typed numbers in big or little endian; and its flush and shutdown.

IoBuf

A buffer an owned write takes: memory at an address that does not move while the runtime holds the buffer, whose first bytes_init bytes are written.

IoBufMut

A buffer an owned read fills: an IoBuf whose memory past the bytes it holds may be written, and told how many hold data after a read.

IoObject

An IO object a Handle takes over: on unix anything with a file descriptor; on Windows std’s TcpStream, TcpListener, UdpSocket and File.

IoVecBuf

The buffers of an owned vectored write: each one’s bytes, in order, go out as one write. Implemented for Vec<B> and [B; N] of any IoBuf, Vec<Vec<u8>> among them.

IoVecBufMut

The buffers of an owned vectored read: the bytes read fill each one’s spare capacity in order. Implemented for Vec<B> and [B; N] of any IoBufMut.

Functions

copy

Copies everything reader gives into writer, then flushes it; answers the bytes copied.

copy_bidirectional

Copies a into b and b into a at once, in the calling task, each direction through a buffer of 8 KiB; a direction whose reader ends closes its writer. Answers the bytes copied each way, (a to b, b to a), once both ended; the first error ends both.

copy_bidirectional_with_sizes

copy_bidirectional with a buffer of a_to_b bytes for one direction and of b_to_a bytes for the other.

copy_buf

Copies everything a buffered reader gives into writer from the reader’s own buffer, then flushes it; answers the bytes copied.

duplex

Two connected in-memory streams, each direction a pipe of max_buf_size bytes: a write waits while its pipe is full.

empty

A reader at its end at once, and a writer that takes every byte and keeps none.

repeat

A reader that gives byte over and over, without end.

simplex

One in-memory pipe of max_buf_size bytes: what the writer writes, the reader reads.

sink

A writer that takes every byte and keeps none.

split

Splits stream into a read half and a write half; ReadHalf::unsplit puts them back together.

stderr

The process’s standard error, as an async stream (see Stderr).

stdin

The process’s standard input, as an async stream (see Stdin).

stdout

The process’s standard output, as an async stream (see Stdout).