.RS File Format – Concurrency and async

Send and Sync

Send and Sync are auto traits and unsafe traits (Reference: Special types and traits).

A type that holds raw pointers can opt in with unsafe impl Send for T {}, promising that doing so is safe. Types used in a non-mut static must be Sync.

Threads

use std::thread;

let handle = thread::spawn(|| {
    println!("hello from a thread");
    42
});
let result = handle.join().unwrap();    // waits, and returns the closure's value

let data = vec![1, 2, 3];
thread::scope(|s| {                     // threads may borrow local data
    s.spawn(|| println!("{:?}", data));
    s.spawn(|| println!("{}", data.len()));
});                                     // all scoped threads are joined here

thread::spawn needs a closure and return value that are Send and 'static, usually written with move. Scoped threads may borrow from the enclosing function. A panic in a spawned thread makes join return Err.

Thread-local storage is declared with the thread_local! macro.

Sharing and synchronisation

use std::sync::{Arc, Mutex};
use std::thread;

let counter = Arc::new(Mutex::new(0));
let mut handles = vec![];

for _ in 0..4 {
    let c = Arc::clone(&counter);
    handles.push(thread::spawn(move || {
        *c.lock().unwrap() += 1;
    }));
}
for h in handles { h.join().unwrap(); }

A Mutex is poisoned when a thread panics while holding it, and later lock calls return Err. Atomic operations take a memory ordering: Relaxed, Acquire, Release, AcqRel or SeqCst. Rust atomics currently follow the same rules as C++20 atomics.

Async functions and blocks

async is available from edition 2018. Calling an async fn does no work at once: it captures its arguments into a value implementing Future, and the body runs when that future is polled. The standard library has no executor, so running futures needs a runtime crate such as Tokio or smol.

async fn fetch() -> u32 { 1 }

// Roughly:
// fn fetch() -> impl Future<Output = u32> { async move { 1 } }

async fn run() -> u32 {
    let x = fetch().await;
    let y = async { x + 1 }.await;      // an async block
    y
}

• An async fn’s return type captures all lifetime parameters, and its body captures all parameters, even unused ones.
• An async block produces a future; async move moves its captures in.
• Async functions may be declared in traits, but such traits are not dyn compatible.
• Async closures implement the AsyncFn, AsyncFnMut and AsyncFnOnce traits.

AwaitExpression: Expression . await

The Future trait

pub trait Future {
    type Output;
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
}

pub enum Poll<T> {
    Ready(T),
    Pending,
}

A future is a state machine that an executor polls. When it is not ready, it returns Poll::Pending and arranges to wake the task through the Waker in cx. A future must not be polled after it has returned Ready; what happens then is up to the implementation. Future and IntoFuture are in the prelude in edition 2024.

Pin and Unpin

An async state machine may hold references into itself across an .await, so it must not move once polling begins. Pin<P> wraps a pointer and promises that the target will not be moved unless its type is Unpin.

• Unpin is an auto trait. Most types are Unpin, so pinning has no effect on them. Futures from async code usually are not.
• Box::pin(value) pins on the heap. The std::pin::pin! macro pins on the stack.
• Pin::new works only for Unpin targets. Pin::new_unchecked is unsafe: the caller promises to keep the value in place.