qubit_io/traits/
async_close.rs

1// =============================================================================
2//    Copyright (c) 2025 - 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8
9use std::io::Result;
10use std::pin::Pin;
11use std::task::Context;
12use std::task::Poll;
13
14use crate::AsyncOutput;
15use crate::CloseFuture;
16
17/// Optional asynchronous capability for gracefully closing an output.
18///
19/// Closing is distinct from dropping the Rust value. Implementations complete
20/// any required buffered output and underlying close operation asynchronously.
21/// This capability remains separate from AsyncOutput because not every output
22/// has a meaningful graceful-close operation.
23pub trait AsyncClose: AsyncOutput {
24    /// Polls the closing of this output.
25    ///
26    /// Before returning [`Poll::Pending`], the implementation must arrange for
27    /// `cx`'s waker to be notified when closing may progress. `WouldBlock` and
28    /// `Interrupted` must not cross this asynchronous boundary. A successful
29    /// result means callers must no longer assume that writing remains valid.
30    ///
31    /// # Parameters
32    ///
33    /// * `cx` - Task context used to register interest when closing is pending.
34    ///
35    /// # Returns
36    ///
37    /// [`Poll::Pending`] or the ready close result.
38    ///
39    /// # Errors
40    ///
41    /// Returns the close error reported by the implementation.
42    fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>;
43
44    /// Creates a future that closes this output.
45    ///
46    /// # Returns
47    ///
48    /// A future that resolves with the close result.
49    #[inline(always)]
50    fn close_async(&mut self) -> CloseFuture<'_, Self>
51    where
52        Self: Sized + Unpin,
53    {
54        CloseFuture::new(Pin::new(self))
55    }
56}
qubit_io/traits/async_close.rs

qubit_io/traits/
async_close.rs
