1 //! Asynchronous sinks 2 //! 3 //! This crate contains the `Sink` trait which allows values to be sent 4 //! asynchronously. 5 6 #![cfg_attr(not(feature = "std"), no_std)] 7 #![warn(missing_docs, missing_debug_implementations, rust_2018_idioms, unreachable_pub)] 8 // It cannot be included in the published code because this lints have false positives in the minimum required version. 9 #![cfg_attr(test, warn(single_use_lifetimes))] 10 #![warn(clippy::all)] 11 #![doc(test(attr(deny(warnings), allow(dead_code, unused_assignments, unused_variables))))] 12 13 #[cfg(feature = "alloc")] 14 extern crate alloc; 15 16 use core::ops::DerefMut; 17 use core::pin::Pin; 18 use core::task::{Context, Poll}; 19 20 /// A `Sink` is a value into which other values can be sent, asynchronously. 21 /// 22 /// Basic examples of sinks include the sending side of: 23 /// 24 /// - Channels 25 /// - Sockets 26 /// - Pipes 27 /// 28 /// In addition to such "primitive" sinks, it's typical to layer additional 29 /// functionality, such as buffering, on top of an existing sink. 30 /// 31 /// Sending to a sink is "asynchronous" in the sense that the value may not be 32 /// sent in its entirety immediately. Instead, values are sent in a two-phase 33 /// way: first by initiating a send, and then by polling for completion. This 34 /// two-phase setup is analogous to buffered writing in synchronous code, where 35 /// writes often succeed immediately, but internally are buffered and are 36 /// *actually* written only upon flushing. 37 /// 38 /// In addition, the `Sink` may be *full*, in which case it is not even possible 39 /// to start the sending process. 40 /// 41 /// As with `Future` and `Stream`, the `Sink` trait is built from a few core 42 /// required methods, and a host of default methods for working in a 43 /// higher-level way. The `Sink::send_all` combinator is of particular 44 /// importance: you can use it to send an entire stream to a sink, which is 45 /// the simplest way to ultimately consume a stream. 46 #[must_use = "sinks do nothing unless polled"] 47 pub trait Sink<Item> { 48 /// The type of value produced by the sink when an error occurs. 49 type Error; 50 51 /// Attempts to prepare the `Sink` to receive a value. 52 /// 53 /// This method must be called and return `Poll::Ready(Ok(()))` prior to 54 /// each call to `start_send`. 55 /// 56 /// This method returns `Poll::Ready` once the underlying sink is ready to 57 /// receive data. If this method returns `Poll::Pending`, the current task 58 /// is registered to be notified (via `cx.waker().wake_by_ref()`) when `poll_ready` 59 /// should be called again. 60 /// 61 /// In most cases, if the sink encounters an error, the sink will 62 /// permanently be unable to receive items. poll_ready(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>63 fn poll_ready(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>; 64 65 /// Begin the process of sending a value to the sink. 66 /// Each call to this function must be preceded by a successful call to 67 /// `poll_ready` which returned `Poll::Ready(Ok(()))`. 68 /// 69 /// As the name suggests, this method only *begins* the process of sending 70 /// the item. If the sink employs buffering, the item isn't fully processed 71 /// until the buffer is fully flushed. Since sinks are designed to work with 72 /// asynchronous I/O, the process of actually writing out the data to an 73 /// underlying object takes place asynchronously. **You *must* use 74 /// `poll_flush` or `poll_close` in order to guarantee completion of a 75 /// send**. 76 /// 77 /// Implementations of `poll_ready` and `start_send` will usually involve 78 /// flushing behind the scenes in order to make room for new messages. 79 /// It is only necessary to call `poll_flush` if you need to guarantee that 80 /// *all* of the items placed into the `Sink` have been sent. 81 /// 82 /// In most cases, if the sink encounters an error, the sink will 83 /// permanently be unable to receive items. start_send(self: Pin<&mut Self>, item: Item) -> Result<(), Self::Error>84 fn start_send(self: Pin<&mut Self>, item: Item) -> Result<(), Self::Error>; 85 86 /// Flush any remaining output from this sink. 87 /// 88 /// Returns `Poll::Ready(Ok(()))` when no buffered items remain. If this 89 /// value is returned then it is guaranteed that all previous values sent 90 /// via `start_send` have been flushed. 91 /// 92 /// Returns `Poll::Pending` if there is more work left to do, in which 93 /// case the current task is scheduled (via `cx.waker().wake_by_ref()`) to wake up when 94 /// `poll_flush` should be called again. 95 /// 96 /// In most cases, if the sink encounters an error, the sink will 97 /// permanently be unable to receive items. poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>98 fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>; 99 100 /// Flush any remaining output and close this sink, if necessary. 101 /// 102 /// Returns `Poll::Ready(Ok(()))` when no buffered items remain and the sink 103 /// has been successfully closed. 104 /// 105 /// Returns `Poll::Pending` if there is more work left to do, in which 106 /// case the current task is scheduled (via `cx.waker().wake_by_ref()`) to wake up when 107 /// `poll_close` should be called again. 108 /// 109 /// If this function encounters an error, the sink should be considered to 110 /// have failed permanently, and no more `Sink` methods should be called. poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>111 fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>; 112 } 113 114 impl<S: ?Sized + Sink<Item> + Unpin, Item> Sink<Item> for &mut S { 115 type Error = S::Error; 116 poll_ready(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>117 fn poll_ready(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { 118 Pin::new(&mut **self).poll_ready(cx) 119 } 120 start_send(mut self: Pin<&mut Self>, item: Item) -> Result<(), Self::Error>121 fn start_send(mut self: Pin<&mut Self>, item: Item) -> Result<(), Self::Error> { 122 Pin::new(&mut **self).start_send(item) 123 } 124 poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>125 fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { 126 Pin::new(&mut **self).poll_flush(cx) 127 } 128 poll_close(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>129 fn poll_close(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { 130 Pin::new(&mut **self).poll_close(cx) 131 } 132 } 133 134 impl<P, Item> Sink<Item> for Pin<P> 135 where 136 P: DerefMut + Unpin, 137 P::Target: Sink<Item>, 138 { 139 type Error = <P::Target as Sink<Item>>::Error; 140 poll_ready(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>141 fn poll_ready(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { 142 self.get_mut().as_mut().poll_ready(cx) 143 } 144 start_send(self: Pin<&mut Self>, item: Item) -> Result<(), Self::Error>145 fn start_send(self: Pin<&mut Self>, item: Item) -> Result<(), Self::Error> { 146 self.get_mut().as_mut().start_send(item) 147 } 148 poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>149 fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { 150 self.get_mut().as_mut().poll_flush(cx) 151 } 152 poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>153 fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { 154 self.get_mut().as_mut().poll_close(cx) 155 } 156 } 157 158 #[cfg(feature = "alloc")] 159 mod if_alloc { 160 use super::*; 161 use core::convert::Infallible as Never; 162 163 impl<T> Sink<T> for alloc::vec::Vec<T> { 164 type Error = Never; 165 poll_ready(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>>166 fn poll_ready(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { 167 Poll::Ready(Ok(())) 168 } 169 start_send(self: Pin<&mut Self>, item: T) -> Result<(), Self::Error>170 fn start_send(self: Pin<&mut Self>, item: T) -> Result<(), Self::Error> { 171 // TODO: impl<T> Unpin for Vec<T> {} 172 unsafe { self.get_unchecked_mut() }.push(item); 173 Ok(()) 174 } 175 poll_flush(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>>176 fn poll_flush(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { 177 Poll::Ready(Ok(())) 178 } 179 poll_close(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>>180 fn poll_close(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { 181 Poll::Ready(Ok(())) 182 } 183 } 184 185 impl<T> Sink<T> for alloc::collections::VecDeque<T> { 186 type Error = Never; 187 poll_ready(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>>188 fn poll_ready(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { 189 Poll::Ready(Ok(())) 190 } 191 start_send(self: Pin<&mut Self>, item: T) -> Result<(), Self::Error>192 fn start_send(self: Pin<&mut Self>, item: T) -> Result<(), Self::Error> { 193 // TODO: impl<T> Unpin for Vec<T> {} 194 unsafe { self.get_unchecked_mut() }.push_back(item); 195 Ok(()) 196 } 197 poll_flush(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>>198 fn poll_flush(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { 199 Poll::Ready(Ok(())) 200 } 201 poll_close(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>>202 fn poll_close(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { 203 Poll::Ready(Ok(())) 204 } 205 } 206 207 impl<S: ?Sized + Sink<Item> + Unpin, Item> Sink<Item> for alloc::boxed::Box<S> { 208 type Error = S::Error; 209 poll_ready(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>210 fn poll_ready(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { 211 Pin::new(&mut **self).poll_ready(cx) 212 } 213 start_send(mut self: Pin<&mut Self>, item: Item) -> Result<(), Self::Error>214 fn start_send(mut self: Pin<&mut Self>, item: Item) -> Result<(), Self::Error> { 215 Pin::new(&mut **self).start_send(item) 216 } 217 poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>218 fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { 219 Pin::new(&mut **self).poll_flush(cx) 220 } 221 poll_close(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>222 fn poll_close(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { 223 Pin::new(&mut **self).poll_close(cx) 224 } 225 } 226 } 227