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

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]);
}

Re-exports

pub use util::copy;

pub use util::null;

pub use util::repeat;

Modules

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.

ReadHalf

The readable half of a value returned from split.

WriteHalf

The writable half of a value returned from split.

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.

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

split

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