compio-io 0.9.0

IO traits for completion based async IO
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

<div align="center">
    <a href='https://compio.rs'>
        <img height="150" src="https://github.com/compio-rs/compio-logo/raw/refs/heads/master/generated/colored-with-text.svg">
    </a>
</div>

---

# compio-io

[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/compio-rs/compio/blob/master/LICENSE)
[![crates.io](https://img.shields.io/crates/v/compio-io)](https://crates.io/crates/compio-io)
[![docs.rs](https://img.shields.io/badge/docs.rs-compio--io-latest)](https://docs.rs/compio-io)
[![Check](https://github.com/compio-rs/compio/actions/workflows/ci_check.yml/badge.svg)](https://github.com/compio-rs/compio/actions/workflows/ci_check.yml)
[![Test](https://github.com/compio-rs/compio/actions/workflows/ci_test.yml/badge.svg)](https://github.com/compio-rs/compio/actions/workflows/ci_test.yml)

IO traits for completion-based async IO.

This crate provides async IO traits designed for completion-based operations. Unlike traditional poll-based async IO traits, these traits work with owned buffers and return both the buffer and the operation result upon completion.

The crate itself is runtime-agnostic and can be used with any completion-based async IO runtime.

## Usage

### For application

Use `compio::io` re-exported from `compio` crate, then use the io traits in your application:

```rust
use compio::io::{AsyncRead, AsyncWrite};
```

### For library

If you are writing libraries that want to support completion-based async IO, you can depend on this crate directly:

```bash
cargo add compio-io
```

Then you can use the io traits in your library:

```rust
use compio_io::{AsyncRead, AsyncWrite};
```

## Content
### 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 en/decoding.
- `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)

### Utils
See docs.rs for detail: `copy`, `null`, `repeat`, `split`, `split_unsync`.