[−][src]Crate async_std
Async version of the Rust standard library
async-std
is a foundation of portable Rust software, a set of minimal and battle-tested
shared abstractions for the broader Rust ecosystem. It offers std types, like
Future
and Stream
, library-defined operations on language primitives,
standard macros, I/O and multithreading, among many other things.
async-std
is available from crates.io. Once included, async-std
can be accessed
in use
statements through the path async_std
, as in use async_std::future
.
How to read this documentation
If you already know the name of what you are looking for, the fastest way to find it is to use the search bar at the top of the page.
Otherwise, you may want to jump to one of these useful sections:
If this is your first time, the documentation for async-std
is
written to be casually perused. Clicking on interesting things should
generally lead you to interesting places. Still, there are important bits
you don't want to miss, so read on for a tour of the async-std
and
its documentation!
Once you are familiar with the contents of async-std
you may
begin to find the verbosity of the prose distracting. At this stage in your
development you may want to press the [-]
button near the top of the
page to collapse it into a more skimmable view.
While you are looking at that [-]
button also notice the [src]
button. Rust's API documentation comes with the source code and you are
encouraged to read it. The async-std
source is generally high
quality and a peek behind the curtains is often enlightening.
Modules in this crate are organized in the same way as in std
, except blocking
functions have been replaced with async functions and threads have been replaced with
lightweight tasks.
You can find more information, reading materials, and other resources here:
What is in the async-std
documentation?
First, async-std
is divided into a number of focused
modules, all listed further down this page. These modules are
the bedrock upon which async Rust is forged, and they have mighty names
like async_std::os
and async_std::task
. Modules' documentation
typically includes an overview of the module along with examples, and are
a smart place to start familiarizing yourself with the library.
Second, async-std
defines The Async Prelude, a small collection
of items - mostly traits - that should be imported into every module of
every async crate. The traits in the prelude are pervasive, making the
prelude documentation a good entry point to learning about the library.
And finally, async-std
exports a number of async macros, and
lists them on this page.
Contributing changes to the documentation
Check out async-std
's contribution guidelines here.
The source for this documentation can be found on GitHub.
To contribute changes, make sure you read the guidelines first, then submit
pull requests for your suggested changes.
Contributions are appreciated! If you see a part of the docs that can be improved, submit a PR, or chat with us first on Discord.
A tour of async-std
The rest of this crate documentation is dedicated to pointing out notable
features of async-std
.
Platform abstractions and I/O
Besides basic data types, async-std
is largely concerned with
abstracting over differences in common platforms, most notably Windows and
Unix derivatives.
Common types of I/O, including files, TCP, UDP, are defined in the
io
, fs
, and net
modules.
The task
module contains async-std
's task abstractions. sync
contains further primitive shared memory types, including channel
,
which contains the channel types for message passing.
Timeouts, intervals, and delays
async-std
provides several methods to manipulate time:
task::sleep
to wait for a duration to pass without blocking.stream::interval
for emitting an event at a set interval.future::timeout
to time-out futures if they don't resolve within a set interval.
Examples
All examples require the "attributes"
feature to be enabled.
This feature is not enabled by default because it significantly impacts
compile times. See task::block_on
for an alternative way to start
executing tasks.
Call an async function from the main function:
async fn say_hello() { println!("Hello, world!"); } #[async_std::main] async fn main() { say_hello().await; }
Await two futures concurrently, and return a tuple of their output:
use async_std::prelude::*; #[async_std::main] async fn main() { let a = async { 1u8 }; let b = async { 2u8 }; assert_eq!(a.join(b).await, (1u8, 2u8)) }
Create a UDP server that echoes back each received message to the sender:
use async_std::net::UdpSocket; #[async_std::main] async fn main() -> std::io::Result<()> { let socket = UdpSocket::bind("127.0.0.1:8080").await?; println!("Listening on {}", socket.local_addr()?); let mut buf = vec![0u8; 1024]; loop { let (recv, peer) = socket.recv_from(&mut buf).await?; let sent = socket.send_to(&buf[..recv], &peer).await?; println!("Sent {} out of {} bytes to {}", sent, recv, peer); } }
Features
Items marked with
unstable
are available only when the unstable
Cargo feature is enabled:
[dependencies.async-std]
version = "1.0.0"
features = ["unstable"]
Items marked with
attributes
are available only when the attributes
Cargo feature is enabled:
[dependencies.async-std]
version = "1.0.0"
features = ["attributes"]
Additionally it's possible to only use the core traits and combinators by
only enabling the std
Cargo feature:
[dependencies.async-std]
version = "1.0.0"
default-features = false
features = ["std"]
Modules
fs | Filesystem manipulation operations. |
future | Asynchronous values. |
io | Traits, helpers, and type definitions for core I/O functionality. |
net | Networking primitives for TCP/UDP communication. |
os | OS-specific extensions. |
path | Cross-platform path manipulation. |
pin | unstable Types that pin data to its location in memory. |
prelude | The async prelude. |
process | unstable A module for working with processes. |
stream | Composable asynchronous iteration. |
sync | Synchronization primitives. |
task | Types and traits for working with asynchronous tasks. |
Macros
eprint | unstable Prints to the standard error. |
eprintln | unstable Prints to the standard error, with a newline. |
unstable Prints to the standard output. | |
println | unstable Prints to the standard output, with a newline. |
task_local | Declares task-local values. |
write | Writes formatted data into a buffer. |
writeln | Write formatted data into a buffer, with a newline appended. |
Attribute Macros
main | attributes Enables an async main function. |
test | attributes Enables an async test function. |