qubit-fs 0.2.2

Provider-neutral synchronous and asynchronous filesystem abstraction 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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Failure for an owning asynchronous whole-file write.
use std::error::Error;
use std::fmt::Display;
use std::fmt::Formatter;

use crate::error::FsError;
use crate::write::WriteFailureState;
/// Error returned by an owning asynchronous whole-file write.
///
/// Recovery ownership remains in the operation even when this error is
/// consumed.
///
/// # Examples
/// ```rust
/// # mod support { include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/common/rustdoc_support.rs")); }
/// # use support::*;
/// # let (filesystem, _) = async_recording_spi::async_recording_file_system(async_recording_spi::AsyncRecordingConfig {
/// #     writer_commit_failure: Some(qubit_fs::write::WriteFailureState::NotPublished),
/// #     ..Default::default()
/// # });
/// # poll_support::ready(async {
/// use qubit_fs::Path;
/// use qubit_fs::write::WriteOptions;
/// use qubit_fs::write::AsyncWriterRecovery;
/// use qubit_fs::write::WriteFailureState;
/// let mut operation = filesystem.begin_write_all(
///     Path::parse("/report")?, b"bytes".to_vec(), WriteOptions::default(),
/// )?;
/// let failure = operation.execute().await.expect_err("fixture commit failure");
/// assert_eq!(WriteFailureState::NotPublished, failure.state());
/// assert_eq!(5, failure.written_bytes());
/// assert!(operation.has_recovery());
/// let cleanup = match operation.recovery().expect("retained session") {
///     AsyncWriterRecovery::Opened(writer) => writer.abort_async().await,
///     AsyncWriterRecovery::Rejected(writer) => writer.abort_async().await,
/// };
/// assert!(cleanup.is_ok());
/// // Application error handling can retain `failure`, `cleanup`, and `operation`.
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// # }).unwrap();
/// ```
#[must_use]
pub struct AsyncWriteAllOperationFailure {
    /// Original contextual error.
    error: FsError,
    /// Publication facts at failure.
    state: WriteFailureState,
    /// Bytes acknowledged by completed writes.
    written_bytes: u64,
}
impl AsyncWriteAllOperationFailure {
    /// Creates a failure with its recovery facts.
    pub(crate) fn new(error: FsError, state: WriteFailureState, written_bytes: u64) -> Self {
        Self {
            error,
            state,
            written_bytes,
        }
    }
    /// Returns the contextual filesystem error.
    #[must_use]
    pub const fn error(&self) -> &FsError {
        &self.error
    }
    /// Returns the publication facts recorded when execution stopped.
    #[must_use]
    pub const fn state(&self) -> WriteFailureState {
        self.state
    }
    /// Returns bytes acknowledged by completed writes before execution stopped.
    #[must_use]
    pub const fn written_bytes(&self) -> u64 {
        self.written_bytes
    }
    /// Consumes the failure and returns its filesystem error.
    ///
    /// This discards publication state and confirmed byte count. The operation
    /// still owns any recovery writer; prefer `into_parts` when recovering.
    #[must_use]
    pub fn into_error(self) -> FsError {
        self.error
    }
    /// Consumes the failure and returns all recovery facts.
    #[must_use]
    pub fn into_parts(self) -> (FsError, WriteFailureState, u64) {
        (self.error, self.state, self.written_bytes)
    }
}
impl Display for AsyncWriteAllOperationFailure {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        self.error.fmt(f)
    }
}
impl std::fmt::Debug for AsyncWriteAllOperationFailure {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("AsyncWriteAllOperationFailure")
            .field("error", &self.error)
            .field("state", &self.state)
            .field("written_bytes", &self.written_bytes)
            .finish()
    }
}
impl Error for AsyncWriteAllOperationFailure {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        Some(&self.error)
    }
}