async_ready/
lib.rs

1#![forbid(unsafe_code, future_incompatible)]
2#![deny(missing_debug_implementations, bad_style)]
3#![deny(missing_docs)]
4#![cfg_attr(test, deny(warnings))]
5
6//! Async readiness traits. Useful when implementing async state machines
7//! that can later be wrapped in dedicated futures.
8//!
9//! ## Example
10//!
11//! ```rust
12//!
13//! use std::pin::Pin;
14//! use std::task::{Context, Poll};
15//! use futures::prelude::*;
16//! use async_ready::AsyncReady;
17//! use std::io;
18//!
19//! struct Fut;
20//!
21//! impl Future for Fut {
22//!   type Output = ();
23//!   fn poll(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Self::Output> {
24//!     Poll::Ready(())
25//!   }
26//! }
27//!
28//! impl AsyncReady for Fut {
29//!   type Ok = ();
30//!   type Err = io::Error;
31//!
32//!   fn poll_ready(
33//!     mut self: Pin<&mut Self>,
34//!     cx: &mut Context<'_>,
35//!   ) -> Poll<Result<Self::Ok, Self::Err>> {
36//!     Poll::Ready(Ok(()))
37//!   }
38//! }
39//! ```
40
41use std::pin::Pin;
42use std::task::{Context, Poll};
43
44/// Determine if the underlying API can be written to.
45pub trait AsyncWriteReady {
46  /// The type of successful values yielded by this trait.
47  type Ok;
48
49  /// The type of failures yielded by this trait.
50  type Err: std::error::Error + Send + Sync;
51
52  /// Check if the underlying API can be written to.
53  fn poll_write_ready(
54    self: Pin<&mut Self>,
55    cx: &mut Context<'_>,
56  ) -> Poll<Result<Self::Ok, Self::Err>>;
57
58  /// A convenience for calling `AsyncWriteReady::poll_write_ready` on `Unpin` types.
59  fn poll_write_ready_unpin(
60    &mut self,
61    cx: &mut Context<'_>,
62  ) -> Poll<Result<Self::Ok, Self::Err>>
63  where
64    Self: Unpin + Sized,
65  {
66    Pin::new(self).poll_write_ready(cx)
67  }
68}
69
70/// Determine if the underlying API can be read from.
71pub trait AsyncReadReady {
72  /// The type of successful values yielded by this trait.
73  type Ok;
74
75  /// The type of failures yielded by this trait.
76  type Err: std::error::Error + Send + Sync;
77
78  /// Check if the underlying API can be read from.
79  fn poll_read_ready(
80    self: Pin<&mut Self>,
81    cx: &mut Context<'_>,
82  ) -> Poll<Result<Self::Ok, Self::Err>>;
83
84  /// A convenience for calling `AsyncReadReady::poll_read_ready` on `Unpin` types.
85  fn poll_read_ready_unpin(
86    &mut self,
87    cx: &mut Context<'_>,
88  ) -> Poll<Result<Self::Ok, Self::Err>>
89  where
90    Self: Unpin + Sized,
91  {
92    Pin::new(self).poll_read_ready(cx)
93  }
94}
95
96/// Determine if a struct is async-ready to yield futures.
97///
98/// This is useful when a `Stream` borrows an internal struct, and the internal
99/// struct is in charge of establishing the io channel. That way the stream and
100/// the readiness can be decoupled.
101///
102/// Once the IO channel is async-ready, `poll_async-ready` should always return
103/// `Poll::Ready`.
104pub trait AsyncReady {
105  /// The type of successful values yielded by this trait.
106  type Ok;
107
108  /// The type of failures yielded by this trait.
109  type Err: std::error::Error + Send + Sync;
110
111  /// Check if the stream can be read from.
112  fn poll_ready(
113    self: Pin<&mut Self>,
114    cx: &mut Context<'_>,
115  ) -> Poll<Result<Self::Ok, Self::Err>>;
116
117  /// A convenience for calling `AsyncReady::poll_ready` on `Unpin` types.
118  fn poll_ready_unpin(
119    &mut self,
120    cx: &mut Context<'_>,
121  ) -> Poll<Result<Self::Ok, Self::Err>>
122  where
123    Self: Unpin + Sized,
124  {
125    Pin::new(self).poll_ready(cx)
126  }
127}
128
129/// Extract an error from the underlying struct that isn't propagated through
130/// regular channels.
131///
132/// This is common in `TcpListener` / `UdsStream` structs where this trait can
133/// be used to access the `SO_ERROR` option on the socket.
134///
135/// Both `Ok` and `Err` are error types. If no error exists `take_error` should
136/// return `Ok(None)`.
137pub trait TakeError {
138  /// The type of successful values yielded by this trait.
139  type Ok: std::error::Error + Send + Sync;
140
141  /// The type of failures yielded by this trait.
142  type Err: std::error::Error + Send + Sync;
143
144  /// Return an underlying error value of the struct.
145  fn take_error(&self) -> Result<Option<Self::Ok>, Self::Err>;
146}
async_ready/lib.rs

async_ready/
lib.rs
