1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
//! A lightweight async prelude. //! //! This crate is a subset of [futures] that compiles an order of magnitude faster, fixes minor //! warts in its API, fills in some obvious gaps, and removes all unsafe code from it. //! //! In short, this crate aims to be more enjoyable than [futures] but still fully compatible with //! it. //! //! [futures]: https://docs.rs/futures //! //! # Examples //! //! Connect to a HTTP website, make a GET request, and pipe the response to the standard output: //! //! ```no_run //! use async_net::TcpStream; //! use blocking::{block_on, Unblock}; //! use futures_lite::*; //! //! fn main() -> io::Result<()> { //! block_on(async { //! let mut stream = TcpStream::connect("example.com:80").await?; //! let req = b"GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n"; //! stream.write_all(req).await?; //! //! let mut stdout = Unblock::new(std::io::stdout()); //! io::copy(&stream, &mut stdout).await?; //! Ok(()) //! }) //! } //! ``` #![forbid(unsafe_code)] #![warn(missing_docs, missing_debug_implementations, rust_2018_idioms)] #[doc(no_inline)] pub use std::future::Future; #[doc(no_inline)] pub use futures_core::Stream; #[doc(no_inline)] pub use futures_io::{AsyncBufRead, AsyncRead, AsyncSeek, AsyncWrite}; #[doc(no_inline)] pub use crate::io::{AsyncBufReadExt, AsyncReadExt, AsyncSeekExt, AsyncWriteExt}; #[doc(no_inline)] pub use crate::stream::StreamExt; pub mod future; pub mod io; pub mod stream; /// Unwraps `Poll<T>` or returns [`Pending`][`std::task::Poll::Pending`]. /// /// # Examples /// /// ``` /// use futures_lite::*; /// use std::pin::Pin; /// use std::task::{Context, Poll}; /// /// // Polls two futures and sums their results. /// fn poll_sum( /// cx: &mut Context<'_>, /// mut a: impl Future<Output = i32> + Unpin, /// mut b: impl Future<Output = i32> + Unpin, /// ) -> Poll<i32> { /// let x = ready!(Pin::new(&mut a).poll(cx)); /// let y = ready!(Pin::new(&mut b).poll(cx)); /// Poll::Ready(x + y) /// } /// ``` #[macro_export] macro_rules! ready { ($e:expr $(,)?) => { match $e { std::task::Poll::Ready(t) => t, std::task::Poll::Pending => return std::task::Poll::Pending, } }; } /// Pins a variable of type `T` on the stack and rebinds it as `Pin<&mut T>`. /// /// ``` /// use futures_lite::*; /// use std::fmt::Debug; /// use std::pin::Pin; /// use std::time::Instant; /// /// // Inspects each invocation of `Future::poll()`. /// async fn inspect<T: Debug>(f: impl Future<Output = T>) -> T { /// pin!(f); /// future::poll_fn(|cx| dbg!(f.as_mut().poll(cx))).await /// } /// /// # blocking::block_on(async { /// let f = async { 1 + 2 }; /// inspect(f).await; /// # }) /// ``` #[macro_export] macro_rules! pin { ($($x:ident),* $(,)?) => { $( let mut $x = $x; #[allow(unused_mut)] let mut $x = unsafe { std::pin::Pin::new_unchecked(&mut $x) }; )* } }