#thread-local-storage #os #primitive #storage-api #lazy-evaluation #per-object #os-backed

os-thread-local

OS-backed thread-local storage. This crate provides a ThreadLocal type as an alternative to std::thread_local! that allows per-object thread-local storage, while providing a similar API. It always uses the thread-local storage primitives provided by the OS.

4 releases

0.1.3 Dec 19, 2019
0.1.2 Oct 25, 2019
0.1.1 Oct 25, 2019
0.1.0 Oct 25, 2019

#1100 in Rust patterns

Download history 14689/week @ 2024-03-25 13029/week @ 2024-04-01 11681/week @ 2024-04-08 12904/week @ 2024-04-15 12967/week @ 2024-04-22 13114/week @ 2024-04-29 13161/week @ 2024-05-06 13202/week @ 2024-05-13 13291/week @ 2024-05-20 13168/week @ 2024-05-27 14992/week @ 2024-06-03 16174/week @ 2024-06-10 14842/week @ 2024-06-17 12882/week @ 2024-06-24 15115/week @ 2024-07-01 16576/week @ 2024-07-08

61,952 downloads per month
Used in 4 crates (3 directly)

Apache-2.0/MIT

27KB
390 lines

OS-backed thread-local storage

This crate provides a ThreadLocal type as an alternative to std::thread_local! that allows per-object thread-local storage, while providing a similar API. It always uses the thread-local storage primitives provided by the OS.

On Unix systems, pthread-based thread-local storage is used.

On Windows, fiber-local storage is used. This acts like thread-local storage when fibers are unused, but also provides per-fiber values after fibers are created with e.g. winapi::um::winbase::CreateFiber.

The thread_local crate is an example of another crate that provides per-object thread-local storage, with a different API, and different features, but with more performance overhead than this one.

Examples

This is the same as the example in the std::thread::LocalKey documentation, but adjusted to use ThreadLocal instead. To use it in a static context, a lazy initializer, such as once_cell::sync::Lazy or lazy_static! is required.

use std::cell::RefCell;
use std::thread;
use once_cell::sync::Lazy;
use os_thread_local::ThreadLocal;

static FOO: Lazy<ThreadLocal<RefCell<u32>>> =
    Lazy::new(|| ThreadLocal::new(|| RefCell::new(1)));

FOO.with(|f| {
    assert_eq!(*f.borrow(), 1);
    *f.borrow_mut() = 2;
});

// each thread starts out with the initial value of 1
let t = thread::spawn(move || {
    FOO.with(|f| {
        assert_eq!(*f.borrow(), 1);
        *f.borrow_mut() = 3;
    });
});

// wait for the thread to complete and bail out on panic
t.join().unwrap();

// we retain our original value of 2 despite the child thread
FOO.with(|f| {
    assert_eq!(*f.borrow(), 2);
});

A variation of the same with scoped threads and per-object thread-local storage:

use std::cell::RefCell;
use crossbeam_utils::thread::scope;
use os_thread_local::ThreadLocal;

struct Foo {
    data: u32,
    tls: ThreadLocal<RefCell<u32>>,
}

let foo = Foo {
    data: 0,
    tls: ThreadLocal::new(|| RefCell::new(1)),
};

foo.tls.with(|f| {
    assert_eq!(*f.borrow(), 1);
    *f.borrow_mut() = 2;
});

scope(|s| {
    // each thread starts out with the initial value of 1
    let foo2 = &foo;
    let t = s.spawn(move |_| {
        foo2.tls.with(|f| {
            assert_eq!(*f.borrow(), 1);
            *f.borrow_mut() = 3;
        });
    });

    // wait for the thread to complete and bail out on panic
    t.join().unwrap();

    // we retain our original value of 2 despite the child thread
    foo.tls.with(|f| {
        assert_eq!(*f.borrow(), 2);
    });
}).unwrap();

Dependencies

~215KB