multipart_write/
lib.rs

1//! # Description
2//!
3//! This crate contains the trait [`MultipartWrite`] and assorted implementations
4//! and convenience combinators.
5//!
6//! A `MultipartWrite` is a similar interface to [`Sink`], except that writing
7//! an item or completing the write both return values.
8//!
9//! [`Sink`]: https://docs.rs/crate/futures-sink/0.3.31
10#![cfg_attr(docsrs, feature(doc_cfg))]
11use std::ops::{Deref, DerefMut};
12use std::pin::Pin;
13use std::task::{Context, Poll};
14
15pub mod io;
16pub mod stream;
17pub mod write;
18
19/// A prelude for this crate.
20pub mod prelude {
21    pub use super::MultipartWrite;
22    pub use super::stream::{self, MultipartStreamExt as _};
23    pub use super::write::{self, MultipartWriteExt as _};
24}
25
26/// `MultipartWrite` is a `Sink`-like interface for asynchronously writing an
27/// object in parts.
28pub trait MultipartWrite<Part> {
29    /// The type of value returned when writing the part began successfully.
30    type Ret;
31
32    /// The type of value returned when all parts are written.
33    type Output;
34
35    /// The type of value returned when an operation fails.
36    type Error;
37
38    /// Attempts to prepare the `MultipartWrite` to receive a new part.
39    ///
40    /// This method must be called and return `Poll::Ready` before each call to
41    /// `start_send`, indicating that the underlying writer is ready to have
42    /// another part written to it.
43    ///
44    /// This method returns `Poll::Pending` when the object being prepared cannot
45    /// accept another part.
46    fn poll_ready(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;
47
48    /// Begin the process of writing a part to this writer, returning the
49    /// associated type confirming this was done successfully.
50    ///
51    /// Like `Sink`, this should be preceded by a call to `poll_ready` that
52    /// returns `Poll::Ready` to ensure that the `MultipartWrite` is ready to
53    /// receive a new part.
54    ///
55    /// # Errors
56    ///
57    /// Errors returned by this method are implementation-specific, but it is
58    /// always an error to call `start_send` when `poll_ready` would return
59    /// `Poll::Pending`.
60    fn start_send(self: Pin<&mut Self>, part: Part) -> Result<Self::Ret, Self::Error>;
61
62    /// Flush any remaining output from the writer.
63    ///
64    /// Returns `Poll::Ready` when no parts remain and `Poll::Pending` if there
65    /// is more work left to do.
66    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;
67
68    /// Complete this writer, returning the output.
69    ///
70    /// This method returns `Poll::Pending` until no buffered, unwritten parts
71    /// remain and the complete output object is available.
72    fn poll_complete(
73        self: Pin<&mut Self>,
74        cx: &mut Context<'_>,
75    ) -> Poll<Result<Self::Output, Self::Error>>;
76}
77
78/// A writer that tracks whether or not the underlying writer should no longer
79/// be polled.
80pub trait FusedMultipartWrite<Part>: MultipartWrite<Part> {
81    /// Returns `true` if the writer should no longer be polled.
82    fn is_terminated(&self) -> bool;
83}
84
85impl<W: ?Sized + MultipartWrite<Part> + Unpin, Part> MultipartWrite<Part> for &mut W {
86    type Ret = W::Ret;
87    type Output = W::Output;
88    type Error = W::Error;
89
90    fn poll_ready(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
91        Pin::new(&mut **self).poll_ready(cx)
92    }
93
94    fn start_send(mut self: Pin<&mut Self>, part: Part) -> Result<Self::Ret, Self::Error> {
95        Pin::new(&mut **self).start_send(part)
96    }
97
98    fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
99        Pin::new(&mut **self).poll_flush(cx)
100    }
101
102    fn poll_complete(
103        mut self: Pin<&mut Self>,
104        cx: &mut Context<'_>,
105    ) -> Poll<Result<Self::Output, Self::Error>> {
106        Pin::new(&mut **self).poll_complete(cx)
107    }
108}
109
110impl<W: ?Sized + FusedMultipartWrite<Part> + Unpin, Part> FusedMultipartWrite<Part> for &mut W {
111    fn is_terminated(&self) -> bool {
112        W::is_terminated(self)
113    }
114}
115
116impl<P, Part> MultipartWrite<Part> for Pin<P>
117where
118    P: DerefMut + Unpin,
119    P::Target: MultipartWrite<Part>,
120{
121    type Ret = <P::Target as MultipartWrite<Part>>::Ret;
122    type Output = <P::Target as MultipartWrite<Part>>::Output;
123    type Error = <P::Target as MultipartWrite<Part>>::Error;
124
125    fn poll_ready(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
126        self.get_mut().as_mut().poll_ready(cx)
127    }
128
129    fn start_send(self: Pin<&mut Self>, part: Part) -> Result<Self::Ret, Self::Error> {
130        self.get_mut().as_mut().start_send(part)
131    }
132
133    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
134        self.get_mut().as_mut().poll_flush(cx)
135    }
136
137    fn poll_complete(
138        self: Pin<&mut Self>,
139        cx: &mut Context<'_>,
140    ) -> Poll<Result<Self::Output, Self::Error>> {
141        self.get_mut().as_mut().poll_complete(cx)
142    }
143}
144
145impl<P, Part> FusedMultipartWrite<Part> for Pin<P>
146where
147    P: DerefMut + Unpin,
148    P::Target: FusedMultipartWrite<Part>,
149{
150    fn is_terminated(&self) -> bool {
151        self.deref().is_terminated()
152    }
153}
multipart_write/lib.rs

multipart_write/
lib.rs
