partial-io
Helpers for testing I/O behavior with partial, interrupted and blocking reads and writes.
This library provides:
PartialReadandPartialWrite, which wrap existingReadandWriteimplementations and allow specifying arbitrary behavior on the nextread,writeorflushcall.- With the optional
futures03andtokio1features,PartialAsyncReadandPartialAsyncWriteto wrap existingAsyncReadandAsyncWriteimplementations. These implementations are task-aware, so they will know how to pause and unpause tasks if they return aWouldBlockerror. - With the optional
proptest1(proptest) andquickcheck1(quickcheck) features, generation of random sequences of operations for property-based testing. See theproptest_typesandquickcheck_typesdocumentation 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 the AsyncRead and AsyncWrite provided by futures03 and tokio1:
- A call to
read_to_endorwrite_allwithin 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 useread_to_endorwrite_all(example fix). - Instances must propagate
Poll::Pendingup, 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-iocan help you write a test. - With the
quickcheck1feature enabled,partial-iocan also help shake out bugs in your wrapper. Seequickcheck_typesfor 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.
Minimum supported Rust version
The minimum supported Rust version (MSRV) is 1.56.
While a crate is pre-release status (0.x.x) it may have its MSRV bumped in a patch release. Once a crate has reached 1.x, any MSRV bump will be accompanied with a new minor version.
Contributing
See the CONTRIBUTING file for how to help out.
License
This project is available under the MIT license.
7 Nov 2, 2023
4 Dec 15, 2022
9 Mar 27, 2024
6 Apr 4, 2023
4 Feb 1, 2022
15 Jan 8, 2023
3 Oct 9, 2023
5 Oct 23, 2023
52 Apr 9, 2023
2 Sep 14, 2022
7 Dec 15, 2022
5 Aug 13, 2023
1 Feb 22, 2022
393 Dec 31, 2022
7 Feb 17, 2023
8 Apr 17, 2023
3 Feb 14, 2024
129 Jul 20, 2024
17 Dec 13, 2021