Summary

Add std::thread::add_spawn_hook to register a hook that runs for newly spawned threads. This will effectively provide us with “inheriting thread locals”, a much requested feature.

thread_local! {
    static MY_THREAD_LOCAL: Cell<u32> = Cell::new(0);
}

std::thread::add_spawn_hook(|_| {
    // Get the value of X in the spawning thread.
    let value = MY_THREAD_LOCAL.get();

    // Set the value of X in the newly spawned thread.
    move || MY_THREAD_LOCAL.set(value)
});

Motivation

Thread local variables are often used for scoped “global” state. For example, a testing framework might store the status or name of the current unit test in a thread local variable, such that multiple tests can be run in parallel in the same process.

However, this information will not be preserved across threads when a unit test will spawn a new thread, which is problematic.

The solution seems to be “inheriting thread locals”: thread locals that are automatically inherited by new threads.

However, adding this property to thread local variables is not easily possible. Thread locals are initialized lazily. And by the time they are initialized, the parent thread might have already disappeared, such that there is no value left to inherit from. Additionally, even if the parent thread was still alive, there is no way to access the value in the parent thread without causing race conditions.

Allowing hooks to be run as part of spawning a thread allows precise control over how thread locals are “inherited”. One could simply clone() them, but one could also add additional information to them, or even add relevant information to some (global) data structure.

For example, not only could a custom testing framework keep track of unit test state even across spawned threads, but a logging/debugging/tracing library could keeps track of which thread spawned which thread to provide more useful information to the user.

Public Interface

For adding a hook:

// In std::thread:

/// Registers a function to run for every newly thread spawned.
///
/// The hook is executed in the parent thread, and returns a function
/// that will be executed in the new thread.
///
/// The hook is called with the `Thread` handle for the new thread.
///
/// The hook will only be added for the current thread and is inherited by the threads it spawns.
/// In other words, adding a hook has no effect on already running threads (other than the current
/// thread) and the threads they might spawn in the future.
///
/// The hooks will run in order, starting with the most recently added.
///
/// # Usage
///
/// ```
/// std::thread::add_spawn_hook(|_| {
///     ..; // This will run in the parent (spawning) thread.
///     move || {
///         ..; // This will run it the child (spawned) thread.
///     }
/// });
/// ```
///
/// # Example
///
/// A spawn hook can be used to "inherit" a thread local from the parent thread:
///
/// ```
/// use std::cell::Cell;
///
/// thread_local! {
///     static X: Cell<u32> = Cell::new(0);
/// }
///
/// // This needs to be done once in the main thread before spawning any threads.
/// std::thread::add_spawn_hook(|_| {
///     // Get the value of X in the spawning thread.
///     let value = X.get();
///     // Set the value of X in the newly spawned thread.
///     move || X.set(value)
/// });
///
/// X.set(123);
///
/// std::thread::spawn(|| {
///     assert_eq!(X.get(), 123);
/// }).join().unwrap();
/// ```
pub fn add_spawn_hook<F, G>(hook: F)
where
    F: 'static + Send + Sync + Fn(&Thread) -> G,
    G: 'static + Send + FnOnce();

And for opting out when spawning a hook:

// In std::thread:

impl Builder {
    /// Disables running and inheriting [spawn hooks](add_spawn_hook).
    ///
    /// Use this if the parent thread is in no way relevant for the child thread.
    /// For example, when lazily spawning threads for a thread pool.
    pub fn no_hooks(mut self) -> Builder;
}

Implementation

The implementation is a thread local linked list of hooks, which is inherited by newly spawned threads. This means that adding a hook will only affect the current thread and all (direct and indirect) future child threads of the current thread. It will not globally affect all already running threads.

Functions that spawn a thread, such as std::thread::spawn will eventually call spawn_unchecked_, which will call the hooks in the parent thread, after the child Thread object has been created, but before the child thread has been spawned. The resulting FnOnce objects are stored and passed on to the child thread afterwards, which will execute them one by one before continuing with its main function.

Downsides

  • The implementation requires allocation for each hook (to store them in the list of hooks), and an allocation each time a hook is spawned (to store the resulting closure).

  • A library that wants to make use of inheriting thread locals will have to register a global hook (e.g. at the start of main), and will need to keep track of whether its hook has already been added.

  • The hooks will not run if threads are spawned through e.g. pthread directly, bypassing the Rust standard library. (However, this is already the case for output capturing in libtest: that does not work across threads when not spawned by libstd.)

Rationale and alternatives

Global vs thread local effect

Unlike e.g. libc’s atexit(), which has a global effect, add_spawn_hook has a thread local effect.

This means that adding a hook will only affect the current thread and all (direct and indirect) future child threads of the current thread. In other words, adding a hook has no effect on already running threads (other than the current thread) and the threads they might spawn in the future.

An alternative could be to have a global set of hooks that affects all newly spawned threads, on any existing and future thread.

Both are relatively easy and efficient to implement (as long as removing hooks is not an option).

The global behavior was proposed in an earlier version of this RFC, but the library-api team expressed a preference for exploring a “more local” solution.

Having a “lexicographically local” solution doesn’t seem to be possible other than for scoped threads, however, since threads can outlive their parent thread and then spawn more threads.

A thread local effect (affecting all future child threads) seems to be the most “local” behavior we can achieve here.

Add but no remove

Having only an add_spawn_hook but not a remove_spawn_hook keeps things simple, by not needing a way to identify a specific hook (through a handle or a name).

If a hook only needs to execute conditionally, one can make use of an if statement.

If no hooks should be executed or inherited, one can use Builder::no_hooks.

Requiring storage on spawning

Because the hooks run on the parent thread first, before the child thread is spawned, the results of those hooks (the functions to be executed in the child) need to be stored. This will require heap allocations (although it might be possible for an optimization to save small objects on the stack up to a certain size).

An alternative interface that wouldn’t require any store is possible, but has downsides. Such an interface would spawn the child thread before running the hooks, and allow the hooks to execute a closure on the child (before it moves on to its main function). That looks roughly like this:

std::thread::add_spawn_hook(|child| {
    // Get the value on the parent thread.
    let value = MY_THREAD_LOCAL.get();
    // Set the value on the child thread.
    child.exec(|| MY_THREAD_LOCAL.set(value));
});

This could be implemented without allocations, as the function executed by the child can now be borrowed from the parent thread.

However, this means that the parent thread will have to block until the child thread has been spawned, and block for each hook to be finished on both threads, significantly slowing down thread creation.

Considering that spawning a thread involves several allocations and syscalls, it doesn’t seem very useful to try to minimize an extra allocation when that comes at a significant cost.

impl vs dyn in the signature

An alternative interface could use dyn instead of generics, as follows:

pub fn add_spawn_hook<F, G>(
    hook: Box<dyn Send + Sync + Fn(&Thread) -> Box<dyn FnOnce() + Send>>
);

However, this mostly has downsides: it requires the user to write Box::new in a few places, and it prevents us from ever implementing some optimization tricks to, for example, use a single allocation for multiple hook results.

A regular function vs some lang feature

Just like std::panic::set_hook, std::thread::add_spawn_hook is just regular function.

An alternative would be to have some special attribute, like #[thread_spawn_hook], similar to #[panic_handler] in no_std programs, or to make use of a potential future global registration feature.

While such things might make sense in a no_std world, spawning threads (like panic hooks) is an std only feature, where we can use global state and allocations.

The only potential advantage of such an approach might be a small reduction in overhead, but this potential overhead is insignificant compared to the overall cost of spwaning a thread.

The downsides are plenty, including limitations on what your hook can do and return, needing a macro or special syntax to register a hook, potential issues with dynamic linking, additional implementation complexity, and possibly having to block on a language feature.

Unresolved questions

  • Should the return value of the hook be an Option, for when the hook does not require any code to be run in the child?

  • Should the hook be able to access/configure more information about the child thread? E.g. set its stack size. (Note that settings that can be changed afterwards by the child thread, such as the thread name, can already be set by simply setting it as part of the code that runs on the child thread.)

Future possibilities

  • Using this in libtest for output capturing (instead of today’s implementation that has special hardcoded support in libstd).

Relevant history

  • The original reason I wrote RFC 3184 “Thread local Cell methods” was to simplify thread spawn hooks (which I was experimenting with at the time). Without that RFC, thread spawn hooks would look something like let v = X.with(|x| x.get()); || X.with(|x| x.set(v)), instead of just let v = X.get(); || X.set(v), which is far less ergonomic (and behaves subtly differently). This is the reason I waited with this RFC until that RFC was merged and stabilized.