# Module std::thread [−] [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 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).

## 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.
- 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:

fn main() { use std::thread; thread::spawn(move || { // some work here }); }

    use std::thread;

    thread::spawn(move || {
        // some work here
    });

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:

fn main() { use std::thread; let child = thread::spawn(move || { // some work here }); // some work here let res = child.join(); }

    use std::thread;

    let child = thread::spawn(move || {
        // some work here
    });
    // some work here
    let res = child.join();

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:

fn main() { #![allow(unused_must_use)] use std::thread; thread::Builder::new().name("child1".to_string()).spawn(move || { println!("Hello, world!"); }); }

    use std::thread;

    thread::Builder::new().name("child1".to_string()).spawn(move || {
        println!("Hello, world!");
    });

## 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. `thread::park_timeout()` does the same, but allows specifying a maximum time to block the thread for.

- The `unpark()` method on a `Thread` 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 which 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.

At a high level, this module provides two variants of storage:

- Owned thread-local storage. This is a type of thread local key which owns the value that it contains, and will destroy the value when the thread exits. This variant is created with the `thread_local!` macro and can contain any value which is `'static` (no borrowed pointers).

- Scoped thread-local storage. This type of key is used to store a reference to a value into local storage temporarily for the scope of a function call. There are no restrictions on what types of values can be placed into this key.

Both forms of thread local storage provide an accessor function, `with`, which will yield a shared reference to the value to the specified closure. Thread-local keys only allow shared access to values as there is no way to guarantee uniqueness if a mutable borrow was 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.
ScopedKey | [Unstable] Type representing a thread local storage key corresponding to a reference to the type parameter `T`.
__ElfLocalKeyInner | [Unstable]
__OsLocalKeyInner | [Unstable]
__ScopedKeyInner | [Unstable]

## 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] Blocks unless or until the current thread's token is made available or the specified duration has been reached (may wake spuriously).
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 `JoinHandle` for it.
yield_now | Cooperatively gives up a timeslice to the OS scheduler.
catch_panic | [Deprecated] Invokes a closure, capturing the cause of panic if one occurs.

## Type Definitions

Result | Indicates the manner in which a thread exited.

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize`)