[−][src]Crate partial_io

Helpers for testing I/O behavior with partial, interrupted and blocking reads and writes.

This library provides:

PartialRead and PartialWrite, which wrap existing Read and Write implementations and allow specifying arbitrary behavior on the next read, write or flush call.
With the optional tokio feature, PartialAsyncRead and PartialAsyncWrite to wrap existing AsyncRead and AsyncWrite implementations. These implementations are task-aware, so they will know how to pause and unpause tasks if they return a WouldBlock error.
With the optional quickcheck feature, generation of random sequences of operations which can be provided to one of the wrappers. See the quickcheck_types documentation for more.

Motivation

A Read or Write wrapper is conceptually simple but can be difficult to get right, especially if the wrapper has an internal buffer. Common issues include:

A partial read or write, even without an error, might leave the wrapper in an invalid state (example fix).

With tokio's AsyncRead and AsyncWrite:

read_to_end or write_all within the wrapper might be partly successful but then error out. These functions will return the error without informing the caller of how much was read or written. Wrappers with an internal buffer will want to advance their state corresponding to the partial success, so they can't use read_to_end or write_all (example fix).
Instances cannot propagate ErrorKind::Interrupted failures up. Wrappers must always retry.
Instances must propagate ErrorKind::WouldBlock failures up, but that shouldn't leave them in an invalid state.

These situations can be hard to think about and hard to test.

partial-io can help in two ways:

For a known bug involving any of these situations, partial-io can help you write a test.
With the quickcheck feature enabled, partial-io can also help shake out bugs in your wrapper. See quickcheck_types for more.

Examples

use std::io::{self, Cursor, Read};

use partial_io::{PartialOp, PartialRead};

let data = b"Hello, world!".to_vec();
let cursor = Cursor::new(data);  // Cursor<Vec<u8>> implements io::Read
let ops = vec![PartialOp::Limited(7), PartialOp::Err(io::ErrorKind::Interrupted)];
let mut partial_read = PartialRead::new(cursor, ops);

let mut out = vec![0; 256];

// The first read will read 7 bytes.
assert_eq!(partial_read.read(&mut out).unwrap(), 7);
assert_eq!(&out[..7], b"Hello, ");
// The second read will fail with ErrorKind::Interrupted.
assert_eq!(partial_read.read(&mut out[7..]).unwrap_err().kind(), io::ErrorKind::Interrupted);
// The iterator has run out of operations, so it no longer truncates reads.
assert_eq!(partial_read.read(&mut out[7..]).unwrap(), 6);
assert_eq!(&out[..13], b"Hello, world!");

For a real-world example, see the tests in zstd-rs.

Re-exports

pub use crate::quickcheck_types::GenError;

pub use crate::quickcheck_types::GenInterrupted;

pub use crate::quickcheck_types::GenInterruptedWouldBlock;

pub use crate::quickcheck_types::GenNoErrors;

pub use crate::quickcheck_types::GenWouldBlock;

pub use crate::quickcheck_types::PartialWithErrors;

Modules

quickcheck_types

QuickCheck support for partial IO operations.

Structs

PartialAsyncRead	A wrapper that breaks inner `AsyncRead` instances up according to the provided iterator.
PartialAsyncWrite	A wrapper that breaks inner `AsyncWrite` instances up according to the provided iterator.
PartialRead	A reader wrapper that breaks inner `Read` instances up according to the provided iterator.
PartialWrite	A writer wrapper that breaks inner `Write` instances up according to the provided iterator.

Enums

PartialOp

What to do the next time an IO operation is performed.