[−][src]Crate humthreads

A rust library built on top of std::thread to provide additional features and tools to make development easier and to support operators.

Spawning threads

Threads are created with a Builder similar to std::thread::Builder.

use std::thread::sleep;
use std::time::Duration;

use humthreads::Builder;

let thread = Builder::new("os-thread-name")
    .spawn(|scope| {
        // This code is run in a separate thread.
        // The `scope` attribute can be used to interact with advanced APIs.
        while !scope.should_shutdown() {
            // Do work in the background
            sleep(Duration::from_millis(10));
        }
    })
    .expect("failed to spawn thread");

// With a humthreads thread we can request the background thread to stop itself.
thread.request_shutdown();
thread.join().expect("background thread paniced");

Inspecting running threads

One of the biggest differences from std::thread is that humthreads provide an API to fetch a list of running threads and inspect some of their properties.

use std::thread::sleep;
use std::time::Duration;

use humthreads::registered_threads;
use humthreads::Builder;

let thread1 = Builder::new("thread1")
    .spawn(|scope| {
        while !scope.should_shutdown() {
            sleep(Duration::from_millis(10));
        }
    })
    .expect("failed to spawn thread1");
let thread2 = Builder::new("thread2")
    .spawn(|scope| {
        while !scope.should_shutdown() {
            sleep(Duration::from_millis(10));
        }
    })
    .expect("failed to spawn thread2");

// Give threads a chance to start or we'll have nothing to inspect.
sleep(Duration::from_millis(20));

// Fetch a snapshot of running threads and print some information.
let threads = registered_threads();
for thread in threads {
    println!("Thread name: {}", thread.name);
    println!("Thread name passed to the OS: {}", thread.short_name);
    println!("Current thread activity: {:?}", thread.activity);
}

// With a humthreads thread we can request the background thread to stop itself.
thread1.request_shutdown();
thread2.request_shutdown();
thread1.join().expect("background thread1 paniced");
thread2.join().expect("background thread2 paniced");

End users of multi-threaded application often wish for a way to understand what the application is doing without having to read the code and study the concurrent actions. This is valuable insight not just in the presence of bugs but also in case of poor performance or simply for users that wish to know more of what is going on under the hood.

Threads must themselves report what they are working on. What humthreads does is provide helpers for developers to make it easy to report and expose current activity for each thread:

use std::thread::sleep;
use std::time::Duration;

use humthreads::Builder;

let thread = Builder::new("os-thread-name")
    .spawn(|scope| {
        // Set the current activity, overriding the current message.
        scope.activity("waiting for work");

        // Simulare looping over messages.
        for task in 0..10 {
            // Change the reported activity for the duration of the scope.
            // The message is reverted to what we set above when `_activity` is dropped.
            let _activity = scope.scoped_activity(format!("processing task {}", task));
            sleep(Duration::from_millis(10));
        }
    })
    .expect("failed to spawn thread");
thread.join().expect("background thread paniced");

Waiting for threads with Select

use std::thread::sleep;
use std::time::Duration;

use crossbeam_channel::Select;

use humthreads::Builder;

let thread1 = Builder::new("thread1")
    .spawn(|_| {
        sleep(Duration::from_millis(50));
    })
    .expect("failed to spawn thread1");
let thread2 = Builder::new("thread2")
    .spawn(|_| {
        sleep(Duration::from_millis(10));
    })
    .expect("failed to spawn thread2");

// Wait for a thread to exit with the Select API.
let mut set = Select::new();
let idx1 = thread1.select_add(&mut set);
let idx2 = thread2.select_add(&mut set);
let op = set.select_timeout(Duration::from_millis(20)).expect("selection to find thread2");
assert_eq!(idx2, op.index());
thread2.select_join(op).expect("thread2 to have exited successfully");

You can also use the Select::ready API and then use Thread::join or Thread::join_timeout to join with the thread.

Structs

Builder	Thread factory to configure the properties of a new thread.
Error	Error information returned by functions in case of errors.
MapThread	Thread handle that maps the return of a join operation.
Thread	Handle on a thread returned by `Builder::spawn`.
ThreadScope	Additional metadata and state for a specific thread.
ThreadScopeActivityGuard	An RAII implementation of a "scoped activity" of a thread.
ThreadStatus	Public view of a point in time status of a thread.

[−][src]Crate humthreads

Spawning threads

Inspecting running threads

Reporting threads activity

Waiting for threads with Select

Structs

Enums

Functions

Type Definitions