qubit-io 0.17.0

Runtime-neutral synchronous and asynchronous item-stream I/O for Rust
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
80
81
82
83
84
85
86
87
88
89

// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================

use std::io::Error;
use std::io::ErrorKind;
use std::io::Result;

use super::async_contract_error::AsyncContractError;

/// Normalizes error kinds forbidden by the asynchronous I/O contract.
///
/// # Parameters
///
/// - `error`: Error reported by an asynchronous I/O implementation.
///
/// # Returns
///
/// Returns an [`ErrorKind::InvalidData`] error retaining the original error for
/// [`ErrorKind::WouldBlock`] and [`ErrorKind::Interrupted`]. Returns every
/// other error unchanged.
#[must_use]
pub(crate) fn normalize_async_error(error: Error) -> Error {
    match error.kind() {
        ErrorKind::WouldBlock => Error::new(
            ErrorKind::InvalidData,
            AsyncContractError::new("asynchronous I/O implementation returned WouldBlock", error),
        ),
        ErrorKind::Interrupted => Error::new(
            ErrorKind::InvalidData,
            AsyncContractError::new("asynchronous I/O implementation returned Interrupted", error),
        ),
        _ => error,
    }
}

/// Validates a count reported by an input implementation.
///
/// # Parameters
///
/// - `read`: Item count reported by the implementation.
/// - `requested`: Maximum item count requested by the caller.
///
/// # Returns
///
/// Returns `Ok(())` when `read` does not exceed `requested`.
///
/// # Errors
///
/// Returns [`ErrorKind::InvalidData`] when `read` exceeds `requested`.
#[inline]
pub(crate) fn validate_read_count(read: usize, requested: usize) -> Result<()> {
    if read > requested {
        return Err(Error::new(
            ErrorKind::InvalidData,
            format!("reader reported {read} items for a {requested}-item buffer"),
        ));
    }
    Ok(())
}

/// Validates a count reported by an output implementation.
///
/// # Parameters
///
/// - `written`: Item count reported by the implementation.
/// - `requested`: Maximum item count requested by the caller.
///
/// # Returns
///
/// Returns `Ok(())` when `written` does not exceed `requested`.
///
/// # Errors
///
/// Returns [`ErrorKind::InvalidData`] when `written` exceeds `requested`.
#[inline]
pub(crate) fn validate_write_count(written: usize, requested: usize) -> Result<()> {
    if written > requested {
        return Err(Error::new(
            ErrorKind::InvalidData,
            format!("writer reported {written} items for a {requested}-item buffer"),
        ));
    }
    Ok(())
}