Merge branch 'master' into add_stdin_lock

Author: k-nasa

.github/workflows/ci.yml

@@ -7,12 +7,13 @@ on:
       - staging
       - trying
 
+env:
+  RUSTFLAGS: -Dwarnings
+
 jobs:
   build_and_test:
     name: Build and test
     runs-on: ${{ matrix.os }}
-    env:
-      RUSTFLAGS: -Dwarnings
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macOS-latest]
@@ -48,8 +49,6 @@ jobs:
   check_fmt_and_docs:
     name: Checking fmt and docs
     runs-on: ubuntu-latest
-    env:
-      RUSTFLAGS: -Dwarnings
     steps:
     - uses: actions/checkout@master
 
@@ -81,20 +80,11 @@ jobs:
   clippy_check:
     name: Clippy check
     runs-on: ubuntu-latest
-    # TODO: There is a lot of warnings
-    # env:
-    #   RUSTFLAGS: -Dwarnings
     steps:
       - uses: actions/checkout@v1
-      - id: component
-        uses: actions-rs/components-nightly@v1
-        with:
-          component: clippy
-      - uses: actions-rs/toolchain@v1
-        with:
-            toolchain: ${{ steps.component.outputs.toolchain }}
-            override: true
-      - run: rustup component add clippy
-      - uses: actions-rs/clippy-check@v1
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Install rust
+        run: rustup update beta && rustup default beta
+      - name: Install clippy
+        run: rustup component add clippy
+      - name: clippy
+        run: cargo clippy --all --features unstable

Cargo.toml

@@ -9,7 +9,7 @@ authors = [
 edition = "2018"
 license = "Apache-2.0/MIT"
 repository = "https://github.com/async-rs/async-std"
-homepage = "https://github.com/async-rs/async-std"
+homepage = "https://async.rs"
 documentation = "https://docs.rs/async-std"
 description = "Async version of the Rust standard library"
 keywords = ["async", "await", "future", "std", "task"]

docs/src/concepts/futures.md

@@ -24,11 +24,7 @@ To sum up: Rust gives us the ability to safely abstract over important propertie
 
 ## An easy view of computation
 
-While computation is a subject to write a whole [book](https://computationbook.com/) about, a very simplified view suffices for us:
-
-- computation is a sequence of composable operations
-- they can branch based on a decision
-- they either run to succession and yield a result, or they can yield an error
+While computation is a subject to write a whole [book](https://computationbook.com/) about, a very simplified view suffices for us: A sequence of composable operations which can branch based on a decision, run to succession and yield a result or yield an error
 
 ## Deferring computation
 
@@ -136,11 +132,11 @@ When executing 2 or more of these functions at the same time, our runtime system
 
 ## Conclusion
 
-Working from values, we searched for something that expresses *working towards a value available sometime later*. From there, we talked about the concept of polling.
+Working from values, we searched for something that expresses *working towards a value available later*. From there, we talked about the concept of polling.
 
 A `Future` is any data type that does not represent a value, but the ability to *produce a value at some point in the future*. Implementations of this are very varied and detailed depending on use-case, but the interface is simple.
 
-Next, we will introduce you to `tasks`, which we need to actually *run* Futures.
+Next, we will introduce you to `tasks`, which we will use to actually *run* Futures.
 
 [^1]: Two parties reading while it is guaranteed that no one is writing is always safe.
 

docs/src/concepts/tasks.md

@@ -80,7 +80,7 @@ Tasks in `async_std` are one of the core abstractions. Much like Rust's `thread`
 
 ## Blocking
 
-`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 Rust's `std` library 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 the concurrent execution model of `async-std`. Essentially, never do this:
+`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 Rust's `std` library 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 of itself bad behaviour, just something that does not mix well with the concurrent execution model of `async-std`. Essentially, never do this:
 
 ```rust,edition2018
 # extern crate async_std;

docs/src/overview/async-std.md

@@ -4,4 +4,4 @@
 
 `async-std` provides an interface to all important primitives: filesystem operations, network operations and concurrency basics like timers. It also exposes a `task` in a model similar to the `thread` module found in the Rust standard lib.  But it does not only include I/O primitives, but also `async/await` compatible versions of primitives like `Mutex`.
 
-[organization]: https://github.com/async-rs/async-std
+[organization]: https://github.com/async-rs

docs/src/overview/stability-guarantees.md

@@ -31,7 +31,7 @@ In general, this crate will be conservative with respect to the minimum supporte
 
 ## Security fixes
 
-Security fixes will be applied to _all_ minor branches of this library in all _supported_ major revisions. This policy might change in the future, in which case we give at least _3 month_ of ahead notice.
+Security fixes will be applied to _all_ minor branches of this library in all _supported_ major revisions. This policy might change in the future, in which case we give a notice at least _3 months_ ahead.
 
 ## Credits
 

examples/a-chat/main.rs

@@ -8,6 +8,6 @@ fn main() -> Result<()> {
     match (args.nth(1).as_ref().map(String::as_str), args.next()) {
         (Some("client"), None) => client::main(),
         (Some("server"), None) => server::main(),
-        _ => Err("Usage: a-chat [client|server]")?,
+        _ => Err("Usage: a-chat [client|server]".into()),
     }
 }

examples/a-chat/server.rs

@@ -45,7 +45,7 @@ async fn connection_loop(mut broker: Sender<Event>, stream: TcpStream) -> Result
     let mut lines = reader.lines();
 
     let name = match lines.next().await {
-        None => Err("peer disconnected immediately")?,
+        None => return Err("peer disconnected immediately".into()),
         Some(line) => line?,
     };
     let (_shutdown_sender, shutdown_receiver) = mpsc::unbounded::<Void>();

src/fs/file.rs

@@ -66,6 +66,23 @@ pub struct File {
 }
 
 impl File {
+    /// Creates an async file handle.
+    pub(crate) fn new(file: std::fs::File, is_flushed: bool) -> File {
+        let file = Arc::new(file);
+
+        File {
+            file: file.clone(),
+            lock: Lock::new(State {
+                file,
+                mode: Mode::Idle,
+                cache: Vec::new(),
+                is_flushed,
+                last_read_err: None,
+                last_write_err: None,
+            }),
+        }
+    }
+
     /// Opens a file in read-only mode.
     ///
     /// See the [`OpenOptions::open`] function for more options.
@@ -96,7 +113,7 @@ impl File {
     pub async fn open<P: AsRef<Path>>(path: P) -> io::Result<File> {
         let path = path.as_ref().to_owned();
         let file = blocking::spawn(move || std::fs::File::open(&path)).await?;
-        Ok(file.into())
+        Ok(File::new(file, true))
     }
 
     /// Opens a file in write-only mode.
@@ -131,7 +148,7 @@ impl File {
     pub async fn create<P: AsRef<Path>>(path: P) -> io::Result<File> {
         let path = path.as_ref().to_owned();
         let file = blocking::spawn(move || std::fs::File::create(&path)).await?;
-        Ok(file.into())
+        Ok(File::new(file, true))
     }
 
     /// Synchronizes OS-internal buffered contents and metadata to disk.
@@ -383,19 +400,7 @@ impl Seek for &File {
 
 impl From<std::fs::File> for File {
     fn from(file: std::fs::File) -> File {
-        let file = Arc::new(file);
-
-        File {
-            file: file.clone(),
-            lock: Lock::new(State {
-                file,
-                mode: Mode::Idle,
-                cache: Vec::new(),
-                is_flushed: false,
-                last_read_err: None,
-                last_write_err: None,
-            }),
-        }
+        File::new(file, false)
     }
 }
 

src/fs/open_options.rs

@@ -284,7 +284,10 @@ impl OpenOptions {
     pub fn open<P: AsRef<Path>>(&self, path: P) -> impl Future<Output = io::Result<File>> {
         let path = path.as_ref().to_owned();
         let options = self.0.clone();
-        async move { blocking::spawn(move || options.open(path).map(|f| f.into())).await }
+        async move {
+            let file = blocking::spawn(move || options.open(path)).await?;
+            Ok(File::new(file, true))
+        }
     }
 }
 

src/future/future.rs

@@ -1,3 +1,11 @@
+cfg_unstable! {
+    mod delay;
+
+    use std::time::Duration;
+
+    use delay::DelayFuture;
+}
+
 extension_trait! {
     use std::pin::Pin;
     use std::ops::{Deref, DerefMut};
@@ -99,6 +107,28 @@ extension_trait! {
     }
 
     pub trait FutureExt: std::future::Future {
+        /// Returns a Future that delays execution for a specified time.
+        ///
+        /// # Examples
+        ///
+        /// ```
+        /// # async_std::task::block_on(async {
+        /// use async_std::prelude::*;
+        /// use async_std::future;
+        /// use std::time::Duration;
+        ///
+        /// let a = future::ready(1).delay(Duration::from_millis(2000));
+        /// dbg!(a.await);
+        /// # })
+        /// ```
+        #[cfg_attr(feature = "docs", doc(cfg(unstable)))]
+        #[cfg(any(feature = "unstable", feature = "docs"))]
+        fn delay(self, dur: Duration) -> impl Future<Output = Self::Output> [DelayFuture<Self>]
+        where
+            Self: Future + Sized
+        {
+            DelayFuture::new(self, dur)
+        }
     }
 
     impl<F: Future + Unpin + ?Sized> Future for Box<F> {

src/future/future/delay.rs

@@ -0,0 +1,43 @@
+use std::pin::Pin;
+use std::time::Duration;
+
+use futures_timer::Delay;
+use pin_project_lite::pin_project;
+
+use crate::future::Future;
+use crate::task::{Context, Poll};
+
+pin_project! {
+    #[doc(hidden)]
+    #[derive(Debug)]
+    pub struct DelayFuture<F> {
+        #[pin]
+        future: F,
+        #[pin]
+        delay: Delay,
+    }
+}
+
+impl<F> DelayFuture<F> {
+    pub fn new(future: F, dur: Duration) -> DelayFuture<F> {
+        let delay = Delay::new(dur);
+
+        DelayFuture { future, delay }
+    }
+}
+
+impl<F: Future> Future for DelayFuture<F> {
+    type Output = F::Output;
+
+    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        let this = self.project();
+
+        match this.delay.poll(cx) {
+            Poll::Pending => Poll::Pending,
+            Poll::Ready(_) => match this.future.poll(cx) {
+                Poll::Ready(v) => Poll::Ready(v),
+                Poll::Pending => Poll::Pending,
+            },
+        }
+    }
+}

src/io/empty.rs

@@ -28,9 +28,10 @@ pub fn empty() -> Empty {
 
 /// A reader that contains no data.
 ///
-/// This reader is constructed by the [`sink`] function.
+/// This reader is created by the [`empty`] function. See its
+/// documentation for more.
 ///
-/// [`sink`]: fn.sink.html
+/// [`empty`]: fn.empty.html
 pub struct Empty {
     _private: (),
 }

src/io/repeat.rs

@@ -29,7 +29,8 @@ pub fn repeat(byte: u8) -> Repeat {
 
 /// A reader which yields one byte over and over and over and over and over and...
 ///
-/// This reader is constructed by the [`repeat`] function.
+/// This reader is created by the [`repeat`] function. See its
+/// documentation for more.
 ///
 /// [`repeat`]: fn.repeat.html
 pub struct Repeat {

src/io/sink.rs

@@ -25,7 +25,8 @@ pub fn sink() -> Sink {
 
 /// A writer that consumes and drops all data.
 ///
-/// This writer is constructed by the [`sink`] function.
+/// This writer is constructed by the [`sink`] function. See its documentation
+/// for more.
 ///
 /// [`sink`]: fn.sink.html
 pub struct Sink {

src/io/stderr.rs

@@ -12,6 +12,12 @@ use crate::task::{blocking, Context, JoinHandle, Poll};
 ///
 /// [`std::io::stderr`]: https://doc.rust-lang.org/std/io/fn.stderr.html
 ///
+/// ### Note: Windows Portability Consideration
+///
+/// When operating in a console, the Windows implementation of this stream does not support
+/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
+/// an error.
+///
 /// # Examples
 ///
 /// ```no_run
@@ -35,12 +41,16 @@ pub fn stderr() -> Stderr {
 
 /// A handle to the standard error of the current process.
 ///
-/// Created by the [`stderr`] function.
+/// This writer is created by the [`stderr`] function. See its documentation for
+/// more.
+///
+/// ### Note: Windows Portability Consideration
 ///
-/// This type is an async version of [`std::io::Stderr`].
+/// When operating in a console, the Windows implementation of this stream does not support
+/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
+/// an error.
 ///
 /// [`stderr`]: fn.stderr.html
-/// [`std::io::Stderr`]: https://doc.rust-lang.org/std/io/struct.Stderr.html
 #[derive(Debug)]
 pub struct Stderr(Mutex<State>);
 

src/io/stdin.rs

@@ -12,6 +12,12 @@ use crate::task::{blocking, Context, JoinHandle, Poll};
 ///
 /// [`std::io::stdin`]: https://doc.rust-lang.org/std/io/fn.stdin.html
 ///
+/// ### Note: Windows Portability Consideration
+///
+/// When operating in a console, the Windows implementation of this stream does not support
+/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
+/// an error.
+///
 /// # Examples
 ///
 /// ```no_run
@@ -36,12 +42,16 @@ pub fn stdin() -> Stdin {
 
 /// A handle to the standard input of the current process.
 ///
-/// Created by the [`stdin`] function.
+/// This reader is created by the [`stdin`] function. See its documentation for
+/// more.
+///
+/// ### Note: Windows Portability Consideration
 ///
-/// This type is an async version of [`std::io::Stdin`].
+/// When operating in a console, the Windows implementation of this stream does not support
+/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
+/// an error.
 ///
 /// [`stdin`]: fn.stdin.html
-/// [`std::io::Stdin`]: https://doc.rust-lang.org/std/io/struct.Stdin.html
 #[derive(Debug)]
 pub struct Stdin(Mutex<State>);