Crate compio_io

This crate provides traits and utilities for completion-based IO.

Contents

Fundamental

• AsyncRead: Async read into a buffer implements IoBufMut
• AsyncReadAt: Async read into a buffer implements IoBufMut with offset
• AsyncWrite: Async write from a buffer implements IoBuf
• AsyncWriteAt: Async write from a buffer implements IoBuf with offset

Buffered IO

• AsyncBufRead: Trait of async read with buffered content
• BufReader: An async reader with internal buffer
• BufWriter: An async writer with internal buffer

Extension

• AsyncReadExt: Extension trait for AsyncRead
• AsyncReadAtExt: Extension trait for AsyncReadAt
• AsyncWriteExt: Extension trait for AsyncWrite
• AsyncWriteAtExt: Extension trait for AsyncWriteAt

Adapters

• framed::Framed: Adapts AsyncRead to Stream and AsyncWrite to Sink, with framed de/encoding.
• [compat::SyncStream]: Adapts async IO to std blocking io (requires compat feature)
• [compat::AsyncStream]: Adapts async IO to [futures_util::io] traits (requires compat feature)

Examples

Read

use compio_buf::BufResult;
use compio_io::AsyncRead;

let mut reader = "Hello, world!".as_bytes();
let (res, buf) = reader.read(Vec::with_capacity(20)).await.unwrap();

assert_eq!(buf.as_slice(), b"Hello, world!");
assert_eq!(res, 13);

Write

Writing to a fixed-size buffer wrapped by Cursor. The implementation will write the content start at the current position:

use std::io::Cursor;

use compio_buf::BufResult;
use compio_io::AsyncWrite;

let mut writer = Cursor::new([0; 6]);
writer.set_position(2);
let (n, buf) = writer.write(vec![1, 1, 1, 1, 1, 1]).await.unwrap();

assert_eq!(n, 4);
assert_eq!(writer.into_inner(), [0, 0, 1, 1, 1, 1]);

Writing to Vec<u8>, which is extendable. Notice that the implementation will append the content to the end:

use compio_buf::BufResult;
use compio_io::AsyncWrite;

let mut writer = vec![1, 2, 3];
let (_, buf) = writer.write(vec![3, 2, 1]).await.unwrap();

assert_eq!(writer, [1, 2, 3, 3, 2, 1]);

This crate doesn’t depend on a specific runtime. It can work with tokio well:

use compio_buf::BufResult;
use compio_io::AsyncWrite;

#[tokio::main(flavor = "current_thread")]
async fn main() {
    let mut writer = vec![1, 2, 3];
    let (_, buf) = writer.write(vec![3, 2, 1]).await.unwrap();

    assert_eq!(writer, [1, 2, 3, 3, 2, 1]);
}

Modules

framed

Framed I/O operations.

util

IO related utilities functions for ease of use.

Structs

BufReader

Wraps a reader and buffers input from AsyncRead

BufWriter

Wraps a writer and buffers its output.

Traits

AsyncBufRead

AsyncBufRead

AsyncRead

AsyncRead

AsyncReadAt

AsyncReadAt

AsyncReadAtExt

Implemented as an extension trait, adding utility methods to all AsyncReadAt types. Callers will tend to import this trait instead of AsyncReadAt.

AsyncReadExt

Implemented as an extension trait, adding utility methods to all AsyncRead types. Callers will tend to import this trait instead of AsyncRead.

AsyncReadManaged

AsyncReadManaged

AsyncReadManagedAt

AsyncReadAtManaged

AsyncWrite

AsyncWrite

AsyncWriteAt

AsyncWriteAt

AsyncWriteAtExt

Implemented as an extension trait, adding utility methods to all AsyncWriteAt types. Callers will tend to import this trait instead of AsyncWriteAt.

AsyncWriteExt

Implemented as an extension trait, adding utility methods to all AsyncWrite types. Callers will tend to import this trait instead of AsyncWrite.

Functions

copy

Asynchronously copies the entire contents of a reader into a writer.

null

Create a new Null reader and writer which acts like a black hole.

repeat

Creates a reader that infinitely repeats one byte.

split

Splits a single value implementing AsyncRead + AsyncWrite into separate AsyncRead and AsyncWrite handles.with internal synchronization.

split_unsync

Splits a single value implementing AsyncRead + AsyncWrite into separate AsyncRead and AsyncWrite handles without internal synchronization (not Send and Sync).