qubit_fs/spi/
opened_async_temp_file.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-created asynchronous temporary-file envelope.
10
11use super::AsyncTempResourceSpi;
12use crate::metadata::OpenedFileInfo;
13
14/// An already-created asynchronous temporary-file handle.
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::{AsyncTempResourceSpi, OpenedAsyncTempFile, PersistRequest, SpiFuture};
22/// use std::pin::Pin;
23///
24/// struct Session;
25/// impl AsyncTempResourceSpi for Session {
26///     fn cleanup<'a>(self: Pin<&'a mut Self>) -> SpiFuture<'a, qubit_fs::error::FsResult<()>> {
27///         Box::pin(async { Ok(()) })
28///     }
29///     fn keep<'a>(
30///         self: Pin<&'a mut Self>,
31///     ) -> SpiFuture<'a, Result<qubit_fs::temp::PersistOutcome, qubit_fs::spi::SpiPersistFailure>> {
32///         Box::pin(async { unreachable!() })
33///     }
34///     fn persist<'a>(
35///         self: Pin<&'a mut Self>,
36///         _: PersistRequest<'a>,
37///     ) -> SpiFuture<'a, Result<qubit_fs::temp::PersistOutcome, qubit_fs::spi::SpiPersistFailure>> {
38///         Box::pin(async { unreachable!() })
39///     }
40/// }
41/// let info = OpenedFileInfo::new(FileSystemId::new("doc")?, Path::parse("/scratch")?)
42///     .with_metadata(FileMetadata::new(FileKind::File));
43/// let _opened = OpenedAsyncTempFile::new(info, Box::new(Session));
44/// # Ok::<(), qubit_fs::FsError>(())
45/// ```
46pub struct OpenedAsyncTempFile {
47    /// Temporary-file identity claimed by the provider.
48    info: OpenedFileInfo,
49    /// Provider lifecycle session.
50    session: Box<dyn AsyncTempResourceSpi>,
51}
52
53impl OpenedAsyncTempFile {
54    /// Wraps an asynchronous temporary-file handle.
55    ///
56    /// # Parameters
57    /// - `info`: Identity claimed for the temporary file.
58    /// - `session`: Provider lifecycle session.
59    ///
60    /// # Returns
61    /// An asynchronous temporary-file envelope for facade validation.
62    #[inline]
63    #[must_use]
64    pub fn new(info: OpenedFileInfo, session: Box<dyn AsyncTempResourceSpi>) -> Self {
65        Self { info, session }
66    }
67
68    /// Returns the immutable provider-opened identity.
69    ///
70    /// # Returns
71    /// The identity claimed by the provider.
72    #[inline]
73    #[must_use]
74    pub const fn info(&self) -> &OpenedFileInfo {
75        &self.info
76    }
77
78    /// Transfers the provider session into the facade handle.
79    ///
80    /// # Returns
81    /// The claimed identity and provider lifecycle session.
82    #[inline]
83    #[must_use]
84    pub(crate) fn into_parts(self) -> (OpenedFileInfo, Box<dyn AsyncTempResourceSpi>) {
85        (self.info, self.session)
86    }
87}
qubit_fs/spi/opened_async_temp_file.rs

qubit_fs/spi/
opened_async_temp_file.rs
