qubit_fs/spi/
opened_async_writer.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8// facade.
9//! Provider-opened asynchronous writer envelope.
10
11use super::AsyncFileWriteSession;
12use crate::metadata::OpenedFileInfo;
13
14/// An already-open asynchronous writer bound to provider identity.
15///
16/// # Examples
17///
18/// ```rust
19/// use qubit_fs::metadata::{FileKind, FileMetadata, FileSystemId, OpenedFileInfo};
20/// use qubit_fs::path::Path;
21/// use qubit_fs::spi::{AsyncFileWriteSession, OpenedAsyncWriter, SpiFuture};
22/// use qubit_fs::write::{WriteAbortOutcome, WriteFailure};
23/// use qubit_io::AsyncOutput;
24/// use std::io::Result as IoResult;
25/// use std::pin::Pin;
26/// use std::task::{Context, Poll};
27///
28/// struct Session;
29/// impl AsyncOutput for Session {
30///     type Item = u8;
31///     unsafe fn poll_write_unchecked(
32///         self: Pin<&mut Self>,
33///         _: &mut Context<'_>,
34///         _: &[u8],
35///         _: usize,
36///         count: usize,
37///     ) -> Poll<IoResult<usize>> {
38///         Poll::Ready(Ok(count))
39///     }
40///     fn poll_flush(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<IoResult<()>> {
41///         Poll::Ready(Ok(()))
42///     }
43/// }
44/// impl AsyncFileWriteSession for Session {
45///     fn commit_async<'a>(
46///         self: Pin<&'a mut Self>,
47///     ) -> SpiFuture<'a, Result<qubit_fs::metadata::WriteOutcome, WriteFailure>> {
48///         Box::pin(async { unreachable!() })
49///     }
50///     fn abort_async<'a>(self: Pin<&'a mut Self>) -> SpiFuture<'a, qubit_fs::error::FsResult<WriteAbortOutcome>> {
51///         Box::pin(async { Ok(WriteAbortOutcome::NotPublished) })
52///     }
53/// }
54/// let info = OpenedFileInfo::new(FileSystemId::new("doc")?, Path::parse("/draft")?)
55///     .with_metadata(FileMetadata::new(FileKind::File));
56/// let writer = OpenedAsyncWriter::new(info, Box::new(Session));
57/// assert_eq!("/draft", writer.info().path().as_str());
58/// # Ok::<(), qubit_fs::FsError>(())
59/// ```
60pub struct OpenedAsyncWriter {
61    /// Resource identity claimed by the provider.
62    info: OpenedFileInfo,
63    /// Provider asynchronous write session.
64    session: Box<dyn AsyncFileWriteSession>,
65}
66
67impl OpenedAsyncWriter {
68    /// Wraps an opened provider writer session and its validated identity.
69    ///
70    /// # Parameters
71    /// - `info`: Identity claimed for the opened resource.
72    /// - `session`: Provider asynchronous writer session.
73    ///
74    /// # Returns
75    /// An opened-writer envelope for facade validation.
76    #[inline]
77    #[must_use]
78    pub fn new(info: OpenedFileInfo, session: Box<dyn AsyncFileWriteSession>) -> Self {
79        Self { info, session }
80    }
81
82    /// Returns the immutable provider-opened identity.
83    ///
84    /// # Returns
85    /// The identity claimed by the provider.
86    #[inline]
87    #[must_use]
88    pub fn info(&self) -> &OpenedFileInfo {
89        &self.info
90    }
91
92    /// Transfers the unvalidated identity and owned session to the facade.
93    pub(crate) fn into_parts(self) -> (OpenedFileInfo, Box<dyn AsyncFileWriteSession>) {
94        (self.info, self.session)
95    }
96}
qubit_fs/spi/opened_async_writer.rs

qubit_fs/spi/
opened_async_writer.rs
