From 4b45918f50c3662270f7e5fac2364a2cda873994 Mon Sep 17 00:00:00 2001 From: Stjepan Glavina Date: Thu, 15 Aug 2019 19:26:10 +0200 Subject: [PATCH 01/11] Remove time module --- examples/stdin-timeout.rs | 5 +- src/future/pending.rs | 7 ++- src/future/ready.rs | 4 +- src/lib.rs | 1 - src/prelude.rs | 28 +--------- src/task/sleep.rs | 7 ++- src/time/mod.rs | 33 ------------ src/time/timeout.rs | 107 -------------------------------------- 8 files changed, 14 insertions(+), 178 deletions(-) delete mode 100644 src/time/mod.rs delete mode 100644 src/time/timeout.rs diff --git a/examples/stdin-timeout.rs b/examples/stdin-timeout.rs index 04b860a..7cc05bf 100644 --- a/examples/stdin-timeout.rs +++ b/examples/stdin-timeout.rs @@ -5,17 +5,18 @@ use std::time::Duration; use async_std::io; -use async_std::prelude::*; use async_std::task; fn main() -> io::Result<()> { + // This async scope times out after 5 seconds. task::block_on(io::timeout(Duration::from_secs(5), async { let stdin = io::stdin(); + // Read a line from the standard input and display it. let mut line = String::new(); stdin.read_line(&mut line).await?; + dbg!(line); - print!("Got line: {}", line); Ok(()) })) } diff --git a/src/future/pending.rs b/src/future/pending.rs index f45199f..57a40ea 100644 --- a/src/future/pending.rs +++ b/src/future/pending.rs @@ -8,10 +8,13 @@ /// use std::time::Duration; /// /// use async_std::future::pending; -/// use async_std::prelude::*; +/// use async_std::io; /// /// let dur = Duration::from_secs(1); -/// assert!(pending::<()>().timeout(dur).await.is_err()); +/// let fut = pending(); +/// +/// let res: io::Result<()> = io::timeout(dur, fut).await; +/// assert!(res.is_err()); /// # /// # }) } /// ``` diff --git a/src/future/ready.rs b/src/future/ready.rs index 7535d50..6438c60 100644 --- a/src/future/ready.rs +++ b/src/future/ready.rs @@ -10,9 +10,9 @@ /// # #![feature(async_await)] /// # fn main() { async_std::task::block_on(async { /// # -/// use async_std::future::ready; +/// use async_std::future; /// -/// assert_eq!(ready(10).await, 10); +/// assert_eq!(future::ready(10).await, 10); /// # /// # }) } /// ``` diff --git a/src/lib.rs b/src/lib.rs index ad1b0e4..ff2468a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -39,6 +39,5 @@ pub mod prelude; pub mod stream; pub mod sync; pub mod task; -pub mod time; pub(crate) mod utils; diff --git a/src/prelude.rs b/src/prelude.rs index eabd92f..38956b9 100644 --- a/src/prelude.rs +++ b/src/prelude.rs @@ -1,30 +1,6 @@ //! The async prelude. //! -//! The prelude re-exports the most commonly used traits in async programming. -//! -//! # Examples -//! -//! Import the prelude to use the [`timeout`] combinator: -//! -//! ```no_run -//! # #![feature(async_await)] -//! # fn main() -> std::io::Result<()> { async_std::task::block_on(async { -//! # -//! use std::time::Duration; -//! -//! use async_std::io; -//! use async_std::prelude::*; -//! -//! let stdin = io::stdin(); -//! let mut line = String::new(); -//! let dur = Duration::from_secs(5); -//! -//! stdin.read_line(&mut line).timeout(dur).await??; -//! # -//! # Ok(()) }) } -//! ``` -//! -//! [`timeout`]: ../time/trait.Timeout.html#method.timeout +//! The prelude re-exports the most commonly used traits in this crate. #[doc(no_inline)] pub use crate::future::Future; @@ -40,5 +16,3 @@ pub use crate::io::Write as _; pub use crate::stream::Stream; #[doc(no_inline)] pub use crate::task_local; -#[doc(no_inline)] -pub use crate::time::Timeout as _; diff --git a/src/task/sleep.rs b/src/task/sleep.rs index a0392be..fa8804e 100644 --- a/src/task/sleep.rs +++ b/src/task/sleep.rs @@ -1,8 +1,7 @@ use std::time::Duration; -use futures::future; - -use crate::time::Timeout; +use crate::future; +use crate::io; /// Sleeps for the specified amount of time. /// @@ -27,5 +26,5 @@ use crate::time::Timeout; /// # }) } /// ``` pub async fn sleep(dur: Duration) { - let _ = future::pending::<()>().timeout(dur).await; + let _: io::Result<()> = io::timeout(dur, future::pending()).await; } diff --git a/src/time/mod.rs b/src/time/mod.rs deleted file mode 100644 index f8f389c..0000000 --- a/src/time/mod.rs +++ /dev/null @@ -1,33 +0,0 @@ -//! Timeouts for async operations. -//! -//! This module is an async extension of [`std::time`]. -//! -//! [`std::time`]: https://doc.rust-lang.org/std/time/index.html -//! -//! # Examples -//! -//! Read a line from stdin with a timeout of 5 seconds. -//! -//! ```no_run -//! # #![feature(async_await)] -//! # fn main() -> std::io::Result<()> { async_std::task::block_on(async { -//! # -//! use std::time::Duration; -//! -//! use async_std::io; -//! use async_std::prelude::*; -//! -//! let stdin = io::stdin(); -//! let mut line = String::new(); -//! -//! let n = stdin -//! .read_line(&mut line) -//! .timeout(Duration::from_secs(5)) -//! .await??; -//! # -//! # Ok(()) }) } -//! ``` - -pub use timeout::{Timeout, TimeoutError}; - -mod timeout; diff --git a/src/time/timeout.rs b/src/time/timeout.rs deleted file mode 100644 index 9f21bcc..0000000 --- a/src/time/timeout.rs +++ /dev/null @@ -1,107 +0,0 @@ -use std::error::Error; -use std::fmt; -use std::pin::Pin; -use std::time::Duration; - -use cfg_if::cfg_if; -use futures_timer::Delay; -use pin_utils::unsafe_pinned; - -use crate::future::Future; -use crate::io; -use crate::task::{Context, Poll}; - -cfg_if! { - if #[cfg(feature = "docs")] { - #[doc(hidden)] - pub struct ImplFuture(std::marker::PhantomData); - - macro_rules! ret { - ($f:tt, $o:ty) => (ImplFuture<$o>); - } - } else { - macro_rules! ret { - ($f:tt, $o:ty) => ($f); - } - } -} - -/// An error returned when a future times out. -#[derive(Clone, Copy, Debug, Eq, PartialEq)] -pub struct TimeoutError; - -impl Error for TimeoutError {} - -impl fmt::Display for TimeoutError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - "future has timed out".fmt(f) - } -} - -impl From for io::Error { - fn from(_: TimeoutError) -> io::Error { - io::Error::new(io::ErrorKind::TimedOut, "future has timed out") - } -} - -/// An extension trait that configures timeouts for futures. -pub trait Timeout: Future + Sized { - /// Awaits a future to completion or times out after a duration of time. - /// - /// # Examples - /// - /// ```no_run - /// # #![feature(async_await)] - /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async { - /// # - /// use std::time::Duration; - /// - /// use async_std::io; - /// use async_std::prelude::*; - /// - /// let stdin = io::stdin(); - /// let mut line = String::new(); - /// - /// let n = stdin - /// .read_line(&mut line) - /// .timeout(Duration::from_secs(5)) - /// .await??; - /// # - /// # Ok(()) }) } - /// ``` - fn timeout(self, dur: Duration) -> ret!(TimeoutFuture, Result) { - TimeoutFuture { - future: self, - delay: Delay::new(dur), - } - } -} - -/// A future that times out after a duration of time. -#[doc(hidden)] -#[allow(missing_debug_implementations)] -pub struct TimeoutFuture { - future: F, - delay: Delay, -} - -impl TimeoutFuture { - unsafe_pinned!(future: F); - unsafe_pinned!(delay: Delay); -} - -impl Future for TimeoutFuture { - type Output = Result; - - fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { - match self.as_mut().future().poll(cx) { - Poll::Ready(v) => Poll::Ready(Ok(v)), - Poll::Pending => match self.delay().poll(cx) { - Poll::Ready(_) => Poll::Ready(Err(TimeoutError)), - Poll::Pending => Poll::Pending, - }, - } - } -} - -impl Timeout for F {} From 79d6ee97f12875cec9bc38a59d3ab97c758ce06f Mon Sep 17 00:00:00 2001 From: Florian Gilcher Date: Fri, 16 Aug 2019 12:30:48 +0200 Subject: [PATCH 02/11] Document panicking and blocking --- docs/src/concepts/tasks.md | 55 +++++++++++++++++++++++++++++++++++--- 1 file changed, 51 insertions(+), 4 deletions(-) diff --git a/docs/src/concepts/tasks.md b/docs/src/concepts/tasks.md index a56cff5..a4238dd 100644 --- a/docs/src/concepts/tasks.md +++ b/docs/src/concepts/tasks.md @@ -60,21 +60,68 @@ For now, it is enough to know that once you `spawn`ed a task, it will continue r Tasks in `async_std` are one of the core abstractions. Much like Rust’s `thread`s, they provide some practical functionality over the raw concept. `Tasks` have a relationship to the runtime, but they are in themselves separate. `async_std` tasks have a number of desirable properties: -- They are single-allocated +- They are allocated in one single allocation - All tasks have a *backchannel*, which allows them to propagate results and errors to the spawning task through the `JoinHandle` - The carry desirable metadata for debugging - They support task local storage -`async_std` s task api handles setup and teardown of a backing runtime for you and doesn’t rely on a runtime being started. +`async_std`s task api handles setup and teardown of a backing runtime for you and doesn’t rely on a runtime being started. ## Blocking -TODO: fill me in +`Task`s are assumed to run _concurrently_, potentially by sharing a thread of execution. This means that operations blocking an _operating system thread_, such as `std::thread::sleep` or io function from Rusts stdlib will _stop execution of all tasks sharing this thread_. Other libraries (such as database drivers) have similar behaviour. Note that _blocking the current thread_ is not in and by itself bad behaviour, just something that does not mix well with they concurrent execution model of `async-std`. Essentially, never do this: + +```rust +fn main() { + task::block_on(async { + // this is std::fs, which blocks + std::fs::read_to_string("test_file"); + }) +} +``` + +If you want to mix operation kinds, consider putting such operations on a `thread`. ## Errors and panics -TODO: fill me in +`Task`s report errors through normal channels: If they are fallible, their `Output` should be of kind `Result`. +In case of `panic`, behaviour differs depending on if there's a reasonable part that addresses the `panic`. If not, the program _aborts_. + +In practice, that means that `block_on` propagates panics to the blocking component: + +```rust +fn main() { + task::block_on(async { + panic!("test"); + }); +} +``` + +``` +thread 'async-task-driver' panicked at 'test', examples/panic.rs:8:9 +note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace. +``` + +While panicing a spawned tasks will abort: + +```rust +task::spawn(async { + panic!("test"); +}); + +task::block_on(async { + task::sleep(Duration::from_millis(10000)).await; +}) +``` + +``` +thread 'async-task-driver' panicked at 'test', examples/panic.rs:8:9 +note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace. +Aborted (core dumped) +``` + +That might seem odd at first, but the other option would be to silently ignore panics in spawned tasks. The current behaviour can be changed by catching panics in the spawned task and reacting with custom behaviour. This gives users the choice of panic handling strategy. ## Conclusion From 1050c8fc440c3c7d7da9209d6418fa0b5e7cabd7 Mon Sep 17 00:00:00 2001 From: Florian Gilcher Date: Fri, 16 Aug 2019 16:24:40 +0200 Subject: [PATCH 03/11] Add security information --- docs/src/security/policy.md | 37 +++++++++++++++++++++++++++++++++---- 1 file changed, 33 insertions(+), 4 deletions(-) diff --git a/docs/src/security/policy.md b/docs/src/security/policy.md index d6285d0..35d43c7 100644 --- a/docs/src/security/policy.md +++ b/docs/src/security/policy.md @@ -2,14 +2,12 @@ Safety is one of the core principles of what we do, and to that end, we would like to ensure that async-std has a secure implementation. Thank you for taking the time to responsibly disclose any issues you find. -All security bugs in async-std distribution should be reported by email to security@ferrous-systems.com. This list is delivered to a small security team. Your email will be acknowledged within 24 hours, and you’ll receive a more detailed response to your email within 48 hours indicating the next steps in handling your report. If you would like, you can encrypt your report using our public key. This key is also On MIT’s keyserver and reproduced below. +All security bugs in async-std distribution should be reported by email to florian.gilcher@ferrous-systems.com. This list is delivered to a small security team. Your email will be acknowledged within 24 hours, and you’ll receive a more detailed response to your email within 48 hours indicating the next steps in handling your report. If you would like, you can encrypt your report using our public key. This key is also On MIT’s keyserver and reproduced below. Be sure to use a descriptive subject line to avoid having your report be missed. After the initial reply to your report, the security team will endeavor to keep you informed of the progress being made towards a fix and full announcement. As recommended by [RFPolicy][rf-policy], these updates will be sent at least every five days. In reality, this is more likely to be every 24-48 hours. If you have not received a reply to your email within 48 hours, or have not heard from the security team for the past five days, there are a few steps you can take (in order): -* Contact the current security coordinator TODO directly. -* Contact the back-up contact TODO directly. * Post on our Community forums Please note that the discussion forums are public areas. When escalating in these venues, please do not discuss your issue. Simply say that you’re trying to get a hold of someone from the security team. @@ -34,4 +32,35 @@ This policy is adapted from the [Rust project](https://www.rust-lang.org/policie ## PGP Key -TODO \ No newline at end of file +``` +-----BEGIN PGP PUBLIC KEY BLOCK----- + +mQENBF1Wu/ABCADJaGt4HwSlqKB9BGHWYKZj/6mTMbmc29vsEOcCSQKo6myCf9zc +sasWAttep4FAUDX+MJhVbBTSq9M1YVxp33Qh5AF0t9SnJZnbI+BZuGawcHDL01xE +bE+8bcA2+szeTTUZCeWwsaoTd/2qmQKvpUCBQp7uBs/ITO/I2q7+xCGXaOHZwUKc +H8SUBLd35nYFtjXAeejoZVkqG2qEjrc9bkZAwxFXi7Fw94QdkNLaCjNfKxZON/qP +A3WOpyWPr3ERk5C5prjEAvrW8kdqpTRjdmzQjsr8UEXb5GGEOo93N4OLZVQ2mXt9 +dfn++GOnOk7sTxvfiDH8Ru5o4zCtKgO+r5/LABEBAAG0UkZsb3JpYW4gR2lsY2hl +ciAoU2VjdXJpdHkgY29udGFjdCBhc3luYy1zdGQpIDxmbG9yaWFuLmdpbGNoZXJA +ZmVycm91cy1zeXN0ZW1zLmNvbT6JATgEEwECACIFAl1Wu/ACGwMGCwkIBwMCBhUI +AgkKCwQWAgMBAh4BAheAAAoJEACXY97PwLtSc0AH/18yvrElVOkG0ADWX7l+JKHH +nMQtYj0Auop8d6TuKBbpwtYhwELrQoITDMV7f2XEnchNsvYxAyBZhIISmXeJboE1 +KzZD1O+4QPXRcXhj+QNsKQ680mrgZXgAI2Y4ptIW9Vyw3jiHu/ZVopvDAt4li+up +3fRJGPAvGu+tclpJmA+Xam23cDj89M7/wHHgKIyT59WgFwyCgibL+NHKwg2Unzou +9uyZQnq6hf62sQTWEZIAr9BQpKmluplNIJHDeECWzZoE9ucE2ZXsq5pq9qojsAMK +yRdaFdpBcD/AxtrTKFeXGS7X7LqaljY/IFBEdJOqVNWpqSLjGWqjSLIEsc1AB0K5 +AQ0EXVa78AEIAJMxBOEEW+2c3CcjFuUfcRsoBsFH3Vk+GwCbjIpNHq/eAvS1yy2L +u10U5CcT5Xb6be3AeCYv00ZHVbEi6VwoauVCSX8qDjhVzQxvNLgQ1SduobjyF6t8 +3M/wTija6NvMKszyw1l2oHepxSMLej1m49DyCDFNiZm5rjQcYnFT4J71syxViqHF +v2fWCheTrHP3wfBAt5zyDet7IZd/EhYAK6xXEwr9nBPjfbaVexm2B8K6hOPNj0Bp +OKm4rcOj7JYlcxrwhMvNnwEue7MqH1oXAsoaC1BW+qs4acp/hHpesweL6Rcg1pED +OJUQd3UvRsqRK0EsorDu0oj5wt6Qp3ZEbPMAEQEAAYkBHwQYAQIACQUCXVa78AIb +DAAKCRAAl2Pez8C7Uv8bB/9scRm2wvzHLbFtcEHaHvlKO1yYfSVqKqJzIKHc7pM2 ++szM8JVRTxAbzK5Xih9SB5xlekixxO2UCJI5DkJ/ir/RCcg+/CAQ8iLm2UcYAgJD +TocKiR5gjNAvUDI4tMrDLLdF+7+RCQGc7HBSxFiNBJVGAztGVh1+cQ0zaCX6Tt33 +1EQtyRcPID0m6+ip5tCJN0dILC0YcwzXGrSgjB03JqItIyJEucdQz6UB84TIAGku +JJl4tktgD9T7Rb5uzRhHCSbLy89DQVvCcKD4B94ffuDW3HO8n8utDusOiZuG4BUf +WdFy6/gTLNiFbTzkq1BBJQMN1nBwGs1sn63RRgjumZ1N +=dIcF +-----END PGP PUBLIC KEY BLOCK----- +``` \ No newline at end of file From 2391db90031d04ad6695cc2ee3e825a6e4c12eb0 Mon Sep 17 00:00:00 2001 From: Florian Gilcher Date: Fri, 16 Aug 2019 16:35:32 +0200 Subject: [PATCH 04/11] Add two chapters as TODO and change intro (#41) --- docs/src/SUMMARY.md | 4 ++-- docs/src/concepts/async-read-write.md | 2 +- docs/src/concepts/streams.md | 2 +- docs/src/introduction.md | 7 +++++++ docs/src/overview.md | 10 ---------- docs/src/overview/async-std.md | 11 ++++++++++- 6 files changed, 21 insertions(+), 15 deletions(-) create mode 100644 docs/src/introduction.md delete mode 100644 docs/src/overview.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 9a6656e..99b849f 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -1,7 +1,7 @@ # Summary -- [Welcome to `async-std`!](./overview.md) - - [`async-std`](./overview/async-std.md) +- [Introduction](./introduction.md) + - [Welcome to `async-std`!](./overview/async-std.md) - [`std::future` and `futures-rs`](./overview/std-and-library-futures.md) - [Stability guarantees](./overview/stability-guarantees.md) - [Async concepts using async-std](./concepts.md) diff --git a/docs/src/concepts/async-read-write.md b/docs/src/concepts/async-read-write.md index 7935429..15675e9 100644 --- a/docs/src/concepts/async-read-write.md +++ b/docs/src/concepts/async-read-write.md @@ -1 +1 @@ -# Async read/write +# TODO: Async read/write diff --git a/docs/src/concepts/streams.md b/docs/src/concepts/streams.md index 80eeccb..7f319c7 100644 --- a/docs/src/concepts/streams.md +++ b/docs/src/concepts/streams.md @@ -1 +1 @@ -# Streams +# TODO: Streams diff --git a/docs/src/introduction.md b/docs/src/introduction.md new file mode 100644 index 0000000..2def6fc --- /dev/null +++ b/docs/src/introduction.md @@ -0,0 +1,7 @@ +# Introduction + +This book serves as high-level documentation for `async-std` and a way of learning async programming in Rust through it. As such, i focusses on the `async-std` and its task model give you. + +Please note that the Rust project provides its own book on asynchronous programming, called ["Asynchronous Programming in Rust"][async-book], which we highly recommend reading along with this book, as it provides a different, wider view on the topic. + +[async-book]: https://rust-lang.github.io/async-book/ \ No newline at end of file diff --git a/docs/src/overview.md b/docs/src/overview.md deleted file mode 100644 index 4c65965..0000000 --- a/docs/src/overview.md +++ /dev/null @@ -1,10 +0,0 @@ -# Welcome to `async-std` - -![async-std logo](./images/horizontal_color.svg) - -`async-std` along with its [supporting libraries][organization] is a library making your life in async programming easier. It provides provide fundamental implementations for downstream libraries and applications alike. The name reflects the approach of this library: it is a closely modeled to the Rust main standard library as possible, replacing all components by async counterparts. - -`async-std` provides an interface to all important primitives: filesystem operations, network operations and concurrency basics like timers. It also exposes an `task` in a model similar to the `thread` module found in the Rust standard lib. But it does not only include io primitives, but also `async/await` compatible versions of primitives like `Mutex`. You can read more about `async-std` in [the overview chapter][overview-std]. - -[organization]: https://github.com/async-rs/async-std -[overview-std]: overview/async-std/ diff --git a/docs/src/overview/async-std.md b/docs/src/overview/async-std.md index 5b8c6cc..4c65965 100644 --- a/docs/src/overview/async-std.md +++ b/docs/src/overview/async-std.md @@ -1 +1,10 @@ -# async-std +# Welcome to `async-std` + +![async-std logo](./images/horizontal_color.svg) + +`async-std` along with its [supporting libraries][organization] is a library making your life in async programming easier. It provides provide fundamental implementations for downstream libraries and applications alike. The name reflects the approach of this library: it is a closely modeled to the Rust main standard library as possible, replacing all components by async counterparts. + +`async-std` provides an interface to all important primitives: filesystem operations, network operations and concurrency basics like timers. It also exposes an `task` in a model similar to the `thread` module found in the Rust standard lib. But it does not only include io primitives, but also `async/await` compatible versions of primitives like `Mutex`. You can read more about `async-std` in [the overview chapter][overview-std]. + +[organization]: https://github.com/async-rs/async-std +[overview-std]: overview/async-std/ From fa407b18c030494e7fe27c936391bd961004688d Mon Sep 17 00:00:00 2001 From: Florian Gilcher Date: Fri, 16 Aug 2019 16:36:44 +0200 Subject: [PATCH 05/11] Http with io timeouts (#42) * Add simple http example with a timeout * Update lib.rs simple http example comment * Move to current io module --- README.md | 36 ++++++++++++++++++++++++++++++++++++ src/lib.rs | 36 ++++++++++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+) diff --git a/README.md b/README.md index 4901f8d..04891f8 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,42 @@ fn main() { } ``` +## Low-Friction Sockets with Built-In Timeouts + +```rust +#![feature(async_await)] + +use std::time::Duration; + +use async_std::{ + prelude::*, + task, + io, + net::TcpStream, +}; + +async fn get() -> io::Result> { + let mut stream = TcpStream::connect("example.com:80").await?; + stream.write_all(b"GET /index.html HTTP/1.0\r\n\r\n").await?; + + let mut buf = vec![]; + + io::timeout(Duration::from_secs(5), async { + stream.read_to_end(&mut buf).await? + Ok(buf) + }) +} + +fn main() { + task::block_on(async { + let raw_response = get().await.expect("request"); + let response = String::from_utf8(raw_response) + .expect("utf8 conversion"); + println!("received: {}", response); + }); +} +``` + ## Take a look around Clone the repo: diff --git a/src/lib.rs b/src/lib.rs index 42216a2..e7f9ee9 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -22,6 +22,42 @@ //! }) //! } //! ``` +//! +//! Use sockets in a familiar way, with low-friction built-in timeouts: +//! +//! ```no_run +//! #![feature(async_await)] +//! +//! use std::time::Duration; +//! +//! use async_std::{ +//! prelude::*, +//! task, +//! io, +//! net::TcpStream, +//! }; +//! +//! async fn get() -> io::Result> { +//! let mut stream = TcpStream::connect("example.com:80").await?; +//! stream.write_all(b"GET /index.html HTTP/1.0\r\n\r\n").await?; +//! +//! let mut buf = vec![]; +//! +//! io::timeout(Duration::from_secs(5), async { +//! stream.read_to_end(&mut buf).await? +//! Ok(buf) +//! }) +//! } +//! +//! fn main() { +//! task::block_on(async { +//! let raw_response = get().await.expect("request"); +//! let response = String::from_utf8(raw_response) +//! .expect("utf8 conversion"); +//! println!("received: {}", response); +//! }); +//! } +//! ``` #![feature(async_await)] #![cfg_attr(feature = "docs", feature(doc_cfg))] From f4ff5443c861a65b17c26ce1fbe3204a6328f5a1 Mon Sep 17 00:00:00 2001 From: Stjepan Glavina Date: Fri, 16 Aug 2019 16:54:39 +0200 Subject: [PATCH 06/11] Prepare for v0.99.0 --- CHANGELOG.md | 3 +++ Cargo.toml | 9 ++++++--- README.md | 12 ++++++------ src/io/timeout.rs | 1 + 4 files changed, 16 insertions(+), 9 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..1d27c71 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,3 @@ +# Version 0.99.0 + +- Initial beta release diff --git a/Cargo.toml b/Cargo.toml index 45149ad..633a47c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,10 @@ [package] name = "async-std" -version = "0.1.0" -authors = ["Stjepan Glavina "] +version = "0.99.0" +authors = [ + "Stjepan Glavina ", + "The async-std Project Developers", +] edition = "2018" license = "Apache-2.0/MIT" repository = "https://github.com/async-rs/async-std" @@ -19,7 +22,7 @@ rustdoc-args = ["--features docs"] docs = [] [dependencies] -async-task = { git = "ssh://git@github.com/async-rs/async-task.git" } +async-task = "1.0.0" cfg-if = "0.1.9" crossbeam-channel = "0.3.9" futures-preview = "0.3.0-alpha.17" diff --git a/README.md b/README.md index 04891f8..d4393ff 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@ # Async version of Rust's standard library -[![Build Status](https://travis-ci.com/async-rs/async-std.svg?branch=master)](https://travis-ci.org/async-rs/async-std) -[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)]( -https://github.com/async-rs/async-std) +[![Build Status](https://travis-ci.com/async-rs/async-std.svg?branch=master)](https://travis-ci.com/async-rs/async-std) +[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](https://github.com/async-rs/async-std) [![Cargo](https://img.shields.io/crates/v/async-std.svg)](https://crates.io/crates/async-std) [![Documentation](https://docs.rs/async-std/badge.svg)](https://docs.rs/async-std) [![chat](https://img.shields.io/discord/598880689856970762.svg?logo=discord)](https://discord.gg/JvZeVNe) -This crate provides an async version of [`std`]. It provides all the interfaces you are used to, but in an async version and ready for Rust's `async/await`-syntax. +This crate provides an async version of [`std`]. It provides all the interfaces you +are used to, but in an async version and ready for Rust's `async`/`await` syntax. [`std`]: https://doc.rust-lang.org/std/index.html @@ -90,10 +90,10 @@ fn main() { Clone the repo: ``` -git clone git@github.com:stjepang/async-std.git && cd async-std +git clone git@github.com:async-rs/async-std.git && cd async-std ``` -Read the docs: +Generate docs: ``` cargo doc --features docs.rs --open diff --git a/src/io/timeout.rs b/src/io/timeout.rs index b35a803..5197981 100644 --- a/src/io/timeout.rs +++ b/src/io/timeout.rs @@ -24,6 +24,7 @@ use crate::task::{Context, Poll}; /// let stdin = io::stdin(); /// let mut line = String::new(); /// let n = stdin.read_line(&mut line).await?; +/// Ok(()) /// }) /// .await?; /// # From 3c42ecab8f063615e7be9bdc29c73e879af634af Mon Sep 17 00:00:00 2001 From: Stjepan Glavina Date: Fri, 16 Aug 2019 16:54:39 +0200 Subject: [PATCH 07/11] Prepare for v0.99.0 --- src/lib.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index 998b653..4fb0c31 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -44,9 +44,10 @@ //! let mut buf = vec![]; //! //! io::timeout(Duration::from_secs(5), async { -//! stream.read_to_end(&mut buf).await? +//! stream.read_to_end(&mut buf).await?; //! Ok(buf) //! }) +//! .await //! } //! //! fn main() { From 0647de5e8d8e7494e671631e3b34f89d639fa827 Mon Sep 17 00:00:00 2001 From: Stjepan Glavina Date: Fri, 16 Aug 2019 17:18:39 +0200 Subject: [PATCH 08/11] Tweak docs --- src/lib.rs | 39 +++------------------------------------ 1 file changed, 3 insertions(+), 36 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 4fb0c31..a9a0685 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,6 +1,7 @@ //! Async version of the Rust standard library. //! //! This crate is an async version of [`std`]. +//! //! Higher-level documentation in the form of the book //! ["Async programming in Rust with async-std"][book] //! is available. @@ -23,42 +24,8 @@ //! } //! ``` //! -//! Use sockets in a familiar way, with low-friction built-in timeouts: -//! -//! ```no_run -//! #![feature(async_await)] -//! -//! use std::time::Duration; -//! -//! use async_std::{ -//! prelude::*, -//! task, -//! io, -//! net::TcpStream, -//! }; -//! -//! async fn get() -> io::Result> { -//! let mut stream = TcpStream::connect("example.com:80").await?; -//! stream.write_all(b"GET /index.html HTTP/1.0\r\n\r\n").await?; -//! -//! let mut buf = vec![]; -//! -//! io::timeout(Duration::from_secs(5), async { -//! stream.read_to_end(&mut buf).await?; -//! Ok(buf) -//! }) -//! .await -//! } -//! -//! fn main() { -//! task::block_on(async { -//! let raw_response = get().await.expect("request"); -//! let response = String::from_utf8(raw_response) -//! .expect("utf8 conversion"); -//! println!("received: {}", response); -//! }); -//! } -//! ``` +//! See [here](https://github.com/async-rs/async-std/tree/master/examples) +//! for more examples. #![feature(async_await)] #![cfg_attr(feature = "docs", feature(doc_cfg))] From 3538b6b681bb2001f4397b60b10f1d7dc60652ad Mon Sep 17 00:00:00 2001 From: Stjepan Glavina Date: Fri, 16 Aug 2019 17:24:00 +0200 Subject: [PATCH 09/11] Fix rustdoc args --- CHANGELOG.md | 4 ++++ Cargo.toml | 4 ++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d27c71..b3bb8b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +# Version 0.99.1 + +- Fix rustdoc args on docs.rs + # Version 0.99.0 - Initial beta release diff --git a/Cargo.toml b/Cargo.toml index 633a47c..8963f98 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "async-std" -version = "0.99.0" +version = "0.99.1" authors = [ "Stjepan Glavina ", "The async-std Project Developers", @@ -16,7 +16,7 @@ categories = ["asynchronous", "concurrency", "network-programming"] [package.metadata.docs.rs] features = ["docs"] -rustdoc-args = ["--features docs"] +rustdoc-args = ["--features", "docs"] [features] docs = [] From d21bac4663f8e22684a757a1e8de6f151ab21342 Mon Sep 17 00:00:00 2001 From: Stjepan Glavina Date: Fri, 16 Aug 2019 17:30:56 +0200 Subject: [PATCH 10/11] Fix rustdoc args --- CHANGELOG.md | 6 +----- Cargo.toml | 4 ++-- 2 files changed, 3 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b3bb8b9..4b9fb9b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,3 @@ -# Version 0.99.1 - -- Fix rustdoc args on docs.rs - -# Version 0.99.0 +# Version 0.99.2 - Initial beta release diff --git a/Cargo.toml b/Cargo.toml index 8963f98..aa07ee6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "async-std" -version = "0.99.1" +version = "0.99.2" authors = [ "Stjepan Glavina ", "The async-std Project Developers", @@ -16,7 +16,7 @@ categories = ["asynchronous", "concurrency", "network-programming"] [package.metadata.docs.rs] features = ["docs"] -rustdoc-args = ["--features", "docs"] +rustdoc-args = ["--cfg", "feature=\"docs\""] [features] docs = [] From 6418bc9849b435c9c6846bd74ebf094ef917ccc1 Mon Sep 17 00:00:00 2001 From: Stjepan Glavina Date: Fri, 16 Aug 2019 17:39:49 +0200 Subject: [PATCH 11/11] Fix failing docs --- CHANGELOG.md | 2 +- Cargo.toml | 2 +- src/io/empty.rs | 5 ++++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4b9fb9b..744ced8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,3 @@ -# Version 0.99.2 +# Version 0.99.3 - Initial beta release diff --git a/Cargo.toml b/Cargo.toml index aa07ee6..d80ab39 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "async-std" -version = "0.99.2" +version = "0.99.3" authors = [ "Stjepan Glavina ", "The async-std Project Developers", diff --git a/src/io/empty.rs b/src/io/empty.rs index 41978bc..4e5236a 100644 --- a/src/io/empty.rs +++ b/src/io/empty.rs @@ -62,7 +62,10 @@ impl AsyncRead for Empty { impl AsyncBufRead for Empty { #[inline] - fn poll_fill_buf(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll> { + fn poll_fill_buf<'a>( + self: Pin<&'a mut Self>, + _: &mut Context<'_>, + ) -> Poll> { Poll::Ready(Ok(&[])) }