qubit_fs/spi/
async_file_write_session.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//! Provider-side asynchronous file write sessions.
9
10use std::pin::Pin;
11
12use qubit_io::AsyncOutput;
13
14use super::SpiFuture;
15use crate::error::FsResult;
16use crate::metadata::WriteOutcome;
17use crate::write::WriteAbortOutcome;
18use crate::write::WriteFailure;
19
20/// Provider session underlying a concrete [`crate::write::AsyncFileWriter`]
21/// handle.
22///
23/// # Examples
24///
25/// ```
26/// use qubit_fs::spi::AsyncFileWriteSession;
27///
28/// fn accepts_session<T: AsyncFileWriteSession>() {}
29/// ```
30pub trait AsyncFileWriteSession: AsyncOutput<Item = u8> + Send {
31    /// Asynchronously publishes bytes accepted by the session.
32    ///
33    /// # Returns
34    /// A future resolving to the actual publication method and atomicity, or a
35    /// typed failure that preserves provider-confirmed publication progress.
36    ///
37    /// # Errors
38    /// Resolves to a typed write failure when publication cannot be confirmed.
39    fn commit_async<'a>(self: Pin<&'a mut Self>) -> SpiFuture<'a, Result<WriteOutcome, WriteFailure>>;
40
41    /// Asynchronously cancels and cleans up this write session.
42    ///
43    /// # Returns
44    /// A future resolving when cleanup is confirmed.
45    ///
46    /// # Errors
47    /// Resolves to the provider cleanup failure with filesystem context.
48    fn abort_async<'a>(self: Pin<&'a mut Self>) -> SpiFuture<'a, FsResult<WriteAbortOutcome>>;
49
50    /// Performs nonblocking local cancellation during writer drop.
51    ///
52    /// The default does nothing. Implementations must not start or block an
53    /// executor, wait for network I/O, or claim remote cleanup completed.
54    ///
55    /// # Parameters
56    /// - `self`: Pinned provider session being abandoned.
57    #[inline]
58    fn cancel_on_drop(self: Pin<&mut Self>) {}
59}
qubit_fs/spi/async_file_write_session.rs

qubit_fs/spi/
async_file_write_session.rs
