qubit_fs/spi/
opened_async_reader.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 reader envelope.
10
11use qubit_io::AsyncInput;
12
13use crate::metadata::OpenedFileInfo;
14use crate::read::AsyncFileReader;
15
16/// An already-open asynchronous reader bound to provider identity.
17///
18/// # Examples
19///
20/// ```rust
21/// use qubit_fs::metadata::{FileKind, FileMetadata, FileSystemId, OpenedFileInfo};
22/// use qubit_fs::path::Path;
23/// use qubit_fs::spi::OpenedAsyncReader;
24///
25/// let info = OpenedFileInfo::new(FileSystemId::new("doc")?, Path::parse("/x")?)
26///     .with_metadata(FileMetadata::new(FileKind::File));
27/// assert!(std::any::type_name::<OpenedAsyncReader>().contains("OpenedAsyncReader"));
28/// assert_eq!("/x", info.path().as_str());
29/// # Ok::<(), qubit_fs::FsError>(())
30/// ```
31pub struct OpenedAsyncReader {
32    /// Resource identity claimed by the provider.
33    info: OpenedFileInfo,
34    /// Provider asynchronous byte-input session.
35    reader: Box<dyn AsyncInput<Item = u8> + Send>,
36}
37
38impl OpenedAsyncReader {
39    /// Wraps a provider-opened reader session and its claimed identity.
40    ///
41    /// # Parameters
42    /// - `info`: Identity claimed for the opened resource.
43    /// - `reader`: Provider asynchronous byte-input session.
44    ///
45    /// # Returns
46    /// An opened-reader envelope for facade validation.
47    #[inline]
48    #[must_use]
49    pub fn new(info: OpenedFileInfo, reader: Box<dyn AsyncInput<Item = u8> + Send>) -> Self {
50        Self { info, reader }
51    }
52
53    /// Returns the immutable provider-opened identity.
54    ///
55    /// # Returns
56    /// The identity claimed by the provider.
57    #[inline]
58    #[must_use]
59    pub fn info(&self) -> &OpenedFileInfo {
60        &self.info
61    }
62
63    /// Transfers the validated reader into the facade handle.
64    ///
65    /// # Returns
66    /// A facade-owned asynchronous reader.
67    #[inline]
68    #[must_use]
69    pub(crate) fn into_reader(self) -> AsyncFileReader {
70        AsyncFileReader::new(self.info, self.reader)
71    }
72}
qubit_fs/spi/opened_async_reader.rs

qubit_fs/spi/
opened_async_reader.rs
