Skip to content

Commit 35fc85a

Browse files
yoshuawuytsStjepan Glavina
yoshuawuyts
and
Stjepan Glavina
committed
clean readme (#331)
* clean readme Signed-off-by: Yoshua Wuyts <[email protected]> * add back features Signed-off-by: Yoshua Wuyts <[email protected]> * Update README.md Co-Authored-By: Stjepan Glavina <[email protected]>
1 parent aed9e2e commit 35fc85a

File tree

1 file changed

+96
-107
lines changed

1 file changed

+96
-107
lines changed

Diff for: ‎README.md

+96-107
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,78 @@
1-
# Async version of the Rust standard library
2-
3-
[![Build Status](https://travis-ci.com/async-rs/async-std.svg?branch=master)](https://travis-ci.com/async-rs/async-std)
4-
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](https://github.com/async-rs/async-std)
5-
[![Cargo](https://img.shields.io/crates/v/async-std.svg)](https://crates.io/crates/async-std)
6-
[![Documentation](https://docs.rs/async-std/badge.svg)](https://docs.rs/async-std)
7-
[![chat](https://img.shields.io/discord/598880689856970762.svg?logo=discord)](https://discord.gg/JvZeVNe)
8-
9-
This crate provides an async version of [`std`]. It provides all the interfaces you
10-
are used to, but in an async version and ready for Rust's `async`/`await` syntax.
1+
<h1 align="center">async-std</h1>
2+
<div align="center">
3+
<strong>
4+
Async version of the Rust standard library
5+
</strong>
6+
</div>
7+
8+
<br />
9+
10+
<div align="center">
11+
<!-- Crates version -->
12+
<a href="https://crates.io/crates/async-std">
13+
<img src="https://img.shields.io/crates/v/async-std.svg?style=flat-square"
14+
alt="Crates.io version" />
15+
</a>
16+
<!-- Downloads -->
17+
<a href="https://crates.io/crates/async-std">
18+
<img src="https://img.shields.io/crates/d/async-std.svg?style=flat-square"
19+
alt="Download" />
20+
</a>
21+
<!-- docs.rs docs -->
22+
<a href="https://docs.rs/async-std">
23+
<img src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square"
24+
alt="docs.rs docs" />
25+
</a>
26+
27+
<a href="https://discord.gg/JvZeVNe">
28+
<img src="https://img.shields.io/discord/598880689856970762.svg?logo=discord&style=flat-square"
29+
alt="chat" />
30+
</a>
31+
</div>
32+
33+
<div align="center">
34+
<h3>
35+
<a href="https://docs.rs/async-std">
36+
API Docs
37+
</a>
38+
<span> | </span>
39+
<a href="https://book.async.rs">
40+
Book
41+
</a>
42+
<span> | </span>
43+
<a href="https://github.com/async-rs/async-std/releases">
44+
Releases
45+
</a>
46+
<span> | </span>
47+
<a href="https://async.rs/contribute">
48+
Contributing
49+
</a>
50+
</h3>
51+
</div>
52+
53+
<br/>
54+
55+
This crate provides an async version of [`std`]. It provides all the interfaces
56+
you are used to, but in an async version and ready for Rust's `async`/`await`
57+
syntax.
1158

1259
[`std`]: https://doc.rust-lang.org/std/index.html
1360

14-
## Documentation
61+
## Features
1562

16-
`async-std` comes with [extensive API documentation][docs] and a [book][book].
63+
- __Modern:__ Built from the ground up for `std::future` and `async/await` with
64+
blazing fast compilation times.
65+
- __Fast:__ Our robust allocator and threadpool designs provide ultra-high
66+
throughput with predictably low latency.
67+
- __Intuitive:__ Complete parity with the stdlib means you only need to learn
68+
APIs once.
69+
- __Clear:__ [Detailed documentation][docs] and [accessible guides][book] mean
70+
using async Rust was never easier.
1771

1872
[docs]: https://docs.rs/async-std
1973
[book]: https://book.async.rs
2074

21-
## Quickstart
22-
23-
Add the following lines to your `Cargo.toml`:
24-
25-
```toml
26-
[dependencies]
27-
async-std = "0.99"
28-
```
29-
30-
Or use [cargo add][cargo-add] if you have it installed:
31-
32-
```sh
33-
$ cargo add async-std
34-
```
35-
36-
[cargo-add]: https://github.com/killercup/cargo-edit
37-
38-
## Hello world
75+
## Examples
3976

4077
```rust
4178
use async_std::task;
@@ -47,96 +84,48 @@ fn main() {
4784
}
4885
```
4986

50-
## Low-Friction Sockets with Built-In Timeouts
51-
52-
```rust
53-
use std::time::Duration;
54-
55-
use async_std::{
56-
prelude::*,
57-
task,
58-
io,
59-
net::TcpStream,
60-
};
61-
62-
async fn get() -> io::Result<Vec<u8>> {
63-
let mut stream = TcpStream::connect("example.com:80").await?;
64-
stream.write_all(b"GET /index.html HTTP/1.0\r\n\r\n").await?;
65-
66-
let mut buf = vec![];
67-
68-
io::timeout(Duration::from_secs(5), async {
69-
stream.read_to_end(&mut buf).await?;
70-
Ok(buf)
71-
}).await
72-
}
73-
74-
fn main() {
75-
task::block_on(async {
76-
let raw_response = get().await.expect("request");
77-
let response = String::from_utf8(raw_response)
78-
.expect("utf8 conversion");
79-
println!("received: {}", response);
80-
});
81-
}
82-
```
83-
84-
## Features
85-
86-
`async-std` is strongly commited to following semver. This means your code won't
87-
break unless _you_ decide to upgrade.
88-
89-
However every now and then we come up with something that we think will work
90-
_great_ for `async-std`, and we want to provide a sneak-peek so you can try it
91-
out. This is what we call _"unstable"_ features. You can try out the unstable
92-
features by enabling the `unstable` feature in your `Cargo.toml` file:
93-
94-
```toml
95-
[dependencies.async-std]
96-
version = "0.99"
97-
features = ["unstable"]
98-
```
99-
100-
Just be careful when using these features, as they may change between
101-
versions.
87+
More examples, including networking and file access, can be found in our
88+
[`examples`] directory.
10289

103-
## Take a look around
90+
[`examples`]: https://github.com/async-rs/async-std/tree/master/examples
10491

105-
Clone the repo:
92+
## Philosophy
10693

107-
```
108-
git clone [email protected]:async-rs/async-std.git && cd async-std
109-
```
94+
We believe Async Rust should be as easy to pick up as Sync Rust. We also believe
95+
that the best API is the one you already know. And finally, we believe that
96+
providing an asynchronous counterpart to the standard library is the best way
97+
stdlib provides a reliable basis for both performance and productivity.
11098

111-
Generate docs:
99+
Async-std is the embodiment of that vision. It combines single-allocation task
100+
creation, with an adaptive lock-free executor, threadpool and network driver to
101+
create a smooth system that processes work at a high pace with low latency,
102+
using Rust's familiar stdlib API.
112103

113-
```
114-
cargo +nightly doc --features docs --open
115-
```
104+
## Installation
116105

117-
Check out the [examples](examples). To run an example:
106+
With [cargo add][cargo-add] installed run:
118107

108+
```sh
109+
$ cargo add async-std
119110
```
120-
cargo +nightly run --example hello-world
121-
```
122-
123-
## Contributing
124111

125-
See [our contribution document][contribution].
112+
We also provide a set of "unstable" features with async-std. See the [features
113+
documentation] on how to enable them.
126114

127-
[contribution]: https://async.rs/contribute
115+
[cargo-add]: https://github.com/killercup/cargo-edit
116+
[features documentation]: https://docs.rs/async-std/#features
128117

129118
## License
130119

131-
Licensed under either of
132-
133-
* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
134-
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
135-
136-
at your option.
120+
<sup>
121+
Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
122+
2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
123+
</sup>
137124

138-
#### Contribution
125+
<br/>
139126

127+
<sub>
140128
Unless you explicitly state otherwise, any contribution intentionally submitted
141-
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
142-
dual licensed as above, without any additional terms or conditions.
129+
for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
130+
be dual licensed as above, without any additional terms or conditions.
131+
</sub>

0 commit comments

Comments
 (0)