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.