Module std::thread 1.0.0
[−]
[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. Threads can be named, and provide some built-in support for low-level synchronization.
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 the 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).
Spawning a thread
A new thread can be spawned using the thread::spawn
function:
use std::thread; thread::spawn(move || { // some work here });Run
In this example, the spawned thread is "detached" from the current thread. This means that it can outlive its parent (the thread that spawned it), unless this parent is the main thread.
The parent thread can also wait on the completion of the child
thread; a call to spawn
produces a JoinHandle
, which provides
a join
method for waiting:
use std::thread; let child = thread::spawn(move || { // some work here }); // some work here let res = child.join();Run
The join
method returns a Result
containing Ok
of the final
value produced by the child thread, or Err
of the value given to
a call to panic!
if the child panicked.
Configuring threads
A new thread can be configured before it is spawned via the Builder
type,
which currently allows you to set the name and stack size for the child thread:
use std::thread; thread::Builder::new().name("child1".to_string()).spawn(move || { println!("Hello, world!"); });Run
The Thread
type
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
function, and callingthread()
on theJoinHandle
. - By requesting the current thread, using the
thread::current
function.
The thread::current()
function is available even for threads not spawned
by the APIs of this module.
Blocking support: park and unpark
Every thread is equipped with some basic low-level blocking support, via the
thread::park()
function and thread::Thread::unpark()
method. park()
blocks the current thread, which can then be resumed from another thread by
calling the unpark()
method on the blocked thread's handle.
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.thread::park_timeout()
does the same, but allows specifying a maximum time to block the thread for.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 very efficiently on many platforms.
Thread-local storage
This module also provides an implementation of thread-local storage for Rust programs. Thread-local storage is a method of storing data into a global variable that each thread in the program will have its own copy of. Threads do not share this data, so accesses do not need to be synchronized.
A thread-local key owns the value it contains and will destroy the value when the
thread exits. It is created with the thread_local!
macro and can contain any
value that is 'static
(no borrowed pointers). It provides an accessor function,
with
, that yields a shared reference to the value to the specified
closure. Thread-local keys allow only shared access to values, as there would be no
way to guarantee uniqueness if mutable borrows were allowed. Most values
will want to make use of some form of interior mutability through the
Cell
or RefCell
types.
Structs
Builder |
Thread configuration. Provides detailed control over the properties and behavior of new threads. |
JoinHandle |
An owned permission to join on a thread (block on its termination). |
LocalKey |
A thread local storage key which owns its contents. |
Thread |
A handle to a thread. |
ThreadId |
[Unstable] A unique identifier for a running thread. |
Enums
LocalKeyState |
[Unstable] Indicator of the state of a thread local storage key. |
Functions
current |
Gets a handle to the thread that invokes it. |
panicking |
Determines whether the current thread is unwinding because of panic. |
park |
Blocks unless or until the current thread's token is made available. |
park_timeout |
Blocks unless or until the current thread's token is made available or the specified duration has been reached (may wake spuriously). |
park_timeout_ms |
[Deprecated] Use park_timeout. |
sleep |
Puts the current thread to sleep for the specified amount of time. |
sleep_ms |
[Deprecated] Puts the current thread to sleep for the specified amount of time. |
spawn |
Spawns a new thread, returning a |
yield_now |
Cooperatively gives up a timeslice to the OS scheduler. |
Type Definitions
Result |
Indicates the manner in which a thread exited. |