Module std::threadUnstable
[-]
[+]
[src]
Native threads
The threading model
An executing Rust program consists of a collection of native OS threads, each with their own stack and local state.
Communication between threads can be done through
channels, Rust's message-passing
types, along with other forms of thread
synchronization and shared-memory data
structures. In particular, types that are guaranteed to be
threadsafe are easily shared between threads using the
atomically-reference-counted container,
Arc
.
Fatal logic errors in Rust cause thread panic, during which a thread will unwind the stack, running destructors and freeing owned resources. Thread panic is unrecoverable from within the panicking thread (i.e. there is no 'try/catch' in Rust), but panic may optionally be detected from a different thread. If the main thread panics the application will exit with a non-zero exit code.
When the main thread of a Rust program terminates, the entire program shuts down, even if other threads are still running. However, this module provides convenient facilities for automatically waiting for the termination of a child thread (i.e., join), described below.
The Thread
type
Already-running threads are represented via the Thread
type, which you can
get in one of two ways:
- By spawning a new thread, e.g. using the
Thread::spawn
constructor; - By requesting the current thread, using the
Thread::current
function.
Threads can be named, and provide some built-in support for low-level synchronization described below.
The Thread::current()
function is available even for threads not spawned
by the APIs of this module.
Spawning a thread
A new thread can be spawned using the Thread::spawn
function:
use std::thread::Thread; let guard = Thread::spawn(move || { println!("Hello, World!"); // some computation here }); let result = guard.join();
The spawn
function doesn't return a Thread
directly; instead, it returns
a join guard from which a Thread
can be extracted. The join guard is an
RAII-style guard that will automatically join the child thread (block until
it terminates) when it is dropped. You can join the child thread in advance
by calling the join
method on the guard, which will also return the result
produced by the thread.
If you instead wish to detach the child thread, allowing it to outlive its
parent, you can use the detach
method on the guard,
A handle to the thread itself is available via the thread
method on the
join guard.
Configuring threads
A new thread can be configured before it is spawned via the Builder
type,
which currently allows you to set the name, stack size, and writers for
println!
and panic!
for the child thread:
use std::thread; thread::Builder::new().name("child1".to_string()).spawn(move || { println!("Hello, world!") }).detach();
Blocking support: park and unpark
Every thread is equipped with some basic low-level blocking support, via the
park
and unpark
functions.
Conceptually, each Thread
handle has an associated token, which is
initially not present:
The
Thread::park()
function blocks the current thread unless or until the token is available for its thread handle, at which point It atomically consumes the token. It may also return spuriously, without consuming the token.The
unpark()
method on aThread
atomically makes the token available if it wasn't already.
In other words, each Thread
acts a bit like a semaphore with initial count
0, except that the semaphore is saturating (the count cannot go above 1),
and can return spuriously.
The API is typically used by acquiring a handle to the current thread,
placing that handle in a shared data structure so that other threads can
find it, and then park
ing. When some desired condition is met, another
thread calls unpark
on the handle.
The motivation for this design is twofold:
It avoids the need to allocate mutexes and condvars when building new synchronization primitives; the threads already provide basic blocking/signaling.
It can be implemented highly efficiently on many platforms.
Structs
Builder | Thread configuation. Provides detailed control over the properties and behavior of new threads. |
JoinGuard | An RAII-style guard that will block until thread termination when dropped. |
Thread | A handle to a thread. |
Type Definitions
Result | Indicates the manner in which a thread exited. |