From 35fc85a157b961aade8ee1d985af2174083fc0bf Mon Sep 17 00:00:00 2001 From: Yoshua Wuyts Date: Tue, 15 Oct 2019 15:27:41 +0200 Subject: [PATCH] clean readme (#331) * clean readme Signed-off-by: Yoshua Wuyts * add back features Signed-off-by: Yoshua Wuyts * Update README.md Co-Authored-By: Stjepan Glavina --- README.md | 203 ++++++++++++++++++++++++++---------------------------- 1 file changed, 96 insertions(+), 107 deletions(-) diff --git a/README.md b/README.md index ae129aa1..7aeaed86 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,78 @@ -# Async version of the Rust standard library - -[![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. +

async-std

+
+ + Async version of the Rust standard library + +
+ +
+ +
+ + + Crates.io version + + + + Download + + + + docs.rs docs + + + + chat + +
+ +
+

+ + API Docs + + | + + Book + + | + + Releases + + | + + Contributing + +

+
+ +
+ +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 -## Documentation +## Features -`async-std` comes with [extensive API documentation][docs] and a [book][book]. +- __Modern:__ Built from the ground up for `std::future` and `async/await` with + blazing fast compilation times. +- __Fast:__ Our robust allocator and threadpool designs provide ultra-high + throughput with predictably low latency. +- __Intuitive:__ Complete parity with the stdlib means you only need to learn + APIs once. +- __Clear:__ [Detailed documentation][docs] and [accessible guides][book] mean + using async Rust was never easier. [docs]: https://docs.rs/async-std [book]: https://book.async.rs -## Quickstart - -Add the following lines to your `Cargo.toml`: - -```toml -[dependencies] -async-std = "0.99" -``` - -Or use [cargo add][cargo-add] if you have it installed: - -```sh -$ cargo add async-std -``` - -[cargo-add]: https://github.com/killercup/cargo-edit - -## Hello world +## Examples ```rust use async_std::task; @@ -47,96 +84,48 @@ fn main() { } ``` -## Low-Friction Sockets with Built-In Timeouts - -```rust -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); - }); -} -``` - -## Features - -`async-std` is strongly commited to following semver. This means your code won't -break unless _you_ decide to upgrade. - -However every now and then we come up with something that we think will work -_great_ for `async-std`, and we want to provide a sneak-peek so you can try it -out. This is what we call _"unstable"_ features. You can try out the unstable -features by enabling the `unstable` feature in your `Cargo.toml` file: - -```toml -[dependencies.async-std] -version = "0.99" -features = ["unstable"] -``` - -Just be careful when using these features, as they may change between -versions. +More examples, including networking and file access, can be found in our +[`examples`] directory. -## Take a look around +[`examples`]: https://github.com/async-rs/async-std/tree/master/examples -Clone the repo: +## Philosophy -``` -git clone git@github.com:async-rs/async-std.git && cd async-std -``` +We believe Async Rust should be as easy to pick up as Sync Rust. We also believe +that the best API is the one you already know. And finally, we believe that +providing an asynchronous counterpart to the standard library is the best way +stdlib provides a reliable basis for both performance and productivity. -Generate docs: +Async-std is the embodiment of that vision. It combines single-allocation task +creation, with an adaptive lock-free executor, threadpool and network driver to +create a smooth system that processes work at a high pace with low latency, +using Rust's familiar stdlib API. -``` -cargo +nightly doc --features docs --open -``` +## Installation -Check out the [examples](examples). To run an example: +With [cargo add][cargo-add] installed run: +```sh +$ cargo add async-std ``` -cargo +nightly run --example hello-world -``` - -## Contributing -See [our contribution document][contribution]. +We also provide a set of "unstable" features with async-std. See the [features +documentation] on how to enable them. -[contribution]: https://async.rs/contribute +[cargo-add]: https://github.com/killercup/cargo-edit +[features documentation]: https://docs.rs/async-std/#features ## License -Licensed under either of - - * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) - * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) - -at your option. + +Licensed under either of Apache License, Version +2.0 or MIT license at your option. + -#### Contribution +
+ Unless you explicitly state otherwise, any contribution intentionally submitted -for inclusion in the work by you, as defined in the Apache-2.0 license, shall be -dual licensed as above, without any additional terms or conditions. +for inclusion in this crate by you, as defined in the Apache-2.0 license, shall +be dual licensed as above, without any additional terms or conditions. +