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

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
// facade.
//! Provider-opened asynchronous writer envelope.

use super::AsyncFileWriteSession;
use crate::metadata::OpenedFileInfo;

/// An already-open asynchronous writer bound to provider identity.
///
/// # Examples
///
/// ```rust
/// use qubit_fs::metadata::{FileKind, FileMetadata, FileSystemId, OpenedFileInfo};
/// use qubit_fs::path::Path;
/// use qubit_fs::spi::{AsyncFileWriteSession, OpenedAsyncWriter, SpiFuture};
/// use qubit_fs::write::{WriteAbortOutcome, WriteFailure};
/// use qubit_io::AsyncOutput;
/// use std::io::Result as IoResult;
/// use std::pin::Pin;
/// use std::task::{Context, Poll};
///
/// struct Session;
/// impl AsyncOutput for Session {
///     type Item = u8;
///     unsafe fn poll_write_unchecked(
///         self: Pin<&mut Self>,
///         _: &mut Context<'_>,
///         _: &[u8],
///         _: usize,
///         count: usize,
///     ) -> Poll<IoResult<usize>> {
///         Poll::Ready(Ok(count))
///     }
///     fn poll_flush(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<IoResult<()>> {
///         Poll::Ready(Ok(()))
///     }
/// }
/// impl AsyncFileWriteSession for Session {
///     fn commit_async<'a>(
///         self: Pin<&'a mut Self>,
///     ) -> SpiFuture<'a, Result<qubit_fs::metadata::WriteOutcome, WriteFailure>> {
///         Box::pin(async { unreachable!() })
///     }
///     fn abort_async<'a>(self: Pin<&'a mut Self>) -> SpiFuture<'a, qubit_fs::error::FsResult<WriteAbortOutcome>> {
///         Box::pin(async { Ok(WriteAbortOutcome::NotPublished) })
///     }
/// }
/// let info = OpenedFileInfo::new(FileSystemId::new("doc")?, Path::parse("/draft")?)
///     .with_metadata(FileMetadata::new(FileKind::File));
/// let writer = OpenedAsyncWriter::new(info, Box::new(Session));
/// assert_eq!("/draft", writer.info().path().as_str());
/// # Ok::<(), qubit_fs::FsError>(())
/// ```
pub struct OpenedAsyncWriter {
    /// Resource identity claimed by the provider.
    info: OpenedFileInfo,
    /// Provider asynchronous write session.
    session: Box<dyn AsyncFileWriteSession>,
}

impl OpenedAsyncWriter {
    /// Wraps an opened provider writer session and its validated identity.
    ///
    /// # Parameters
    /// - `info`: Identity claimed for the opened resource.
    /// - `session`: Provider asynchronous writer session.
    ///
    /// # Returns
    /// An opened-writer envelope for facade validation.
    #[inline]
    #[must_use]
    pub fn new(info: OpenedFileInfo, session: Box<dyn AsyncFileWriteSession>) -> Self {
        Self { info, session }
    }

    /// Returns the immutable provider-opened identity.
    ///
    /// # Returns
    /// The identity claimed by the provider.
    #[inline]
    #[must_use]
    pub fn info(&self) -> &OpenedFileInfo {
        &self.info
    }

    /// Transfers the unvalidated identity and owned session to the facade.
    pub(crate) fn into_parts(self) -> (OpenedFileInfo, Box<dyn AsyncFileWriteSession>) {
        (self.info, self.session)
    }
}