Struct Thread

1.0.0 · Source

pub struct Thread { /* private fields */ }

Expand description

A handle to a thread.

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 calling thread on the JoinHandle.
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.

There is usually no need to create a Thread struct yourself, one should instead use a function like spawn to create new threads, see the docs of Builder and spawn for more details.

Implementations§

Source §

impl Thread

1.0.0 · Source

pub fn unpark(&self)

Atomically makes the handle’s token available if it is not already.

Every thread is equipped with some basic low-level blocking support, via the park function and the unpark() method. These can be used as a more CPU-efficient implementation of a spinlock.

See the park documentation for more details.

§Examples

use std::thread;
use std::time::Duration;
use std::sync::atomic::{AtomicBool, Ordering};

static QUEUED: AtomicBool = AtomicBool::new(false);

let parked_thread = thread::Builder::new()
    .spawn(|| {
        println!("Parking thread");
        QUEUED.store(true, Ordering::Release);
        thread::park();
        println!("Thread unparked");
    })
    .unwrap();

// Let some time pass for the thread to be spawned.
thread::sleep(Duration::from_millis(10));

// Wait until the other thread is queued.
// This is crucial! It guarantees that the `unpark` below is not consumed
// by some other code in the parked thread (e.g. inside `println!`).
while !QUEUED.load(Ordering::Acquire) {
    // Spinning is of course inefficient; in practice, this would more likely be
    // a dequeue where we have no work to do if there's nobody queued.
    std::hint::spin_loop();
}

println!("Unpark the thread");
parked_thread.thread().unpark();

parked_thread.join().unwrap();

1.19.0 · Source

pub fn id(&self) -> ThreadId

Gets the thread’s unique identifier.

§Examples

use std::thread;

let other_thread = thread::spawn(|| {
    thread::current().id()
});

let other_thread_id = other_thread.join().unwrap();
assert!(thread::current().id() != other_thread_id);

Source

pub fn os_id(&self) -> Option<u64>

🔬This is a nightly-only experimental API. (thread_os_id #160215)

Gets the id the operating system gave this thread, if it has one that can be read.

This is the id that shows up in tools like ps and top, debuggers and crash logs, unlike ThreadId, which has no guaranteed relationship to it. On a platform with no OS-visible thread id, such as SGX, the value may be some other per-thread value (there, the thread’s address), which such tools will not recognize. None means no id could be recorded: the thread has not started running yet, or the platform has no way to read one.

The operating system may reuse the id of a thread that has exited, and a Thread handle can outlive the thread it refers to. After a fork, the id recorded in the child process still refers to the parent’s thread; it is not re-read. Use the id only where a reused or stale id is harmless, such as logging.

§Examples

#![feature(thread_os_id)]
use std::thread;

let spawned = thread::spawn(|| thread::current().os_id()).join().unwrap();
if spawned.is_some() {
    assert_ne!(spawned, thread::current().os_id());
}

1.0.0 · Source

pub fn name(&self) -> Option<&str>

Gets the thread’s name.

For more information about named threads, see this module-level documentation.

§Examples

Threads by default have no name specified:

use std::thread;

let builder = thread::Builder::new();

let handler = builder.spawn(|| {
    assert!(thread::current().name().is_none());
}).unwrap();

handler.join().unwrap();

Thread with a specified name:

use std::thread;

let builder = thread::Builder::new()
    .name("foo".into());

let handler = builder.spawn(|| {
    assert_eq!(thread::current().name(), Some("foo"))
}).unwrap();

handler.join().unwrap();

Source

pub fn into_raw(self) -> *const ()

🔬This is a nightly-only experimental API. (thread_raw #97523)

Consumes the Thread, returning a raw pointer.

To avoid a memory leak the pointer must be converted back into a Thread using Thread::from_raw. The pointer is guaranteed to be aligned to at least 8 bytes.

§Examples

#![feature(thread_raw)]

use std::thread::{self, Thread};

let thread = thread::current();
let id = thread.id();
let ptr = Thread::into_raw(thread);
unsafe {
    assert_eq!(Thread::from_raw(ptr).id(), id);
}

Source