dropping-thread-local 0.1.3

A dynamically allocated ThreadLocal that ensures destructors are run on thread exit
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

# dropping-thread-local [![Latest Version]][crates.io]

[Latest Version]: https://img.shields.io/crates/v/dropping-thread-local.svg
[crates.io]: https://crates.io/crates/dropping-thread-local
<!-- cargo-rdme start -->

Dynamically allocated thread locals that properly run destructors when a thread is destroyed.

This is in contrast to the [`thread_local`] crate, which has similar functionality,
but only runs destructors when the `ThreadLocal` object is dropped.
This crate guarantees that one thread will never see the thread-local data of another,
which can happen in the `thread_local` crate due to internal storage reuse.

This crate attempts to implement "true" thread locals,
mirroring [`std::thread_local!`] as closely as possible.
I would say the `thread_local` crate is good for functionality like reusing allocations
or for having local caches that can be sensibly reused once a thread dies.

This crate will attempt to run destructors as promptly as possible,
but taking snapshots may interfere with this (see below).
Panics in thread destructors will cause aborts, just like they do with [`std::thread_local!`].

Right now, this crate has no unsafe code.
This may change if it can bring a significant performance improvement.

## Snapshots
The most complicated feature of this library is snapshots.
It allows anyone who has access to a [`DroppingThreadLocal`] to iterate over all currently live
values using the [`DroppingThreadLocal::snapshot_iter`] method.

This will return a snapshot of the live values at the time the method is called,
although if a thread dies during iteration, it may not show up.
See the method documentation for more details.

## Performance
Benchmarks show that lookup is 10x and 30x slower than the [`thread_local`] crate, which is in turn about 2x slower than [`std::thread_local!`].

Keep in mind that using a `std::thread_local` is a very fast operation.
It takes about 0.5 nanoseconds on both my M1 Mac and a Intel i5 from 2017.
For reference, calling [`Arc::clone`] takes about 11 ns on both machines.

See `performance.md` in the repository root for benchmarks results and more detailed
performance notes.

### Locking
The implementation needs to acquire a global lock to initialize/deinitialize threads and create new locals.
Accessing thread-local data is also protected by a per-thread lock.
This lock should be uncontended, and [`parking_lot::Mutex`] should make this relatively fast.
I have been careful to make sure that locks are not held while user code is being executed.
This includes releasing locks before any destructors are executed.

## Limitations
The type that is stored must be `Send + Sync + 'static`.
The `Send` bound is necessary because the [`DroppingThreadLocal`] may be dropped from any thread.
The `Sync` bound is necessary to support snapshots,
and the `'static` bound is due to internal implementation chooses (use of safe code).

A Mutex can be used to work around the `Sync` limitation.
(I recommend [`parking_lot::Mutex`], which is optimized for uncontented locks)
You can attempt to use the [`fragile`] crate to work around the `Send` limitation,
but this will cause panics if the value is dropped from another thead.
Some ways a value can be dropped from another thread if a snapshot keeps the value alive,
or if the [`DroppingThreadLocal`] itself is dropped.

[`thread_local`]: https://docs.rs/thread_local/1.1/thread_local/
[`fragile`]: https://docs.rs/fragile/2/fragile/

<!-- cargo-rdme end -->

<!-- cargo inline doc references -->
[`std::thread_local!`]: https://doc.rust-lang.org/std/macro.thread_local.html
[`parking_lot::Mutex`]: https://docs.rs/parking_lot/latest/parking_lot/type.Mutex.html
[`DroppingThreadLocal`]: https://docs.rs/dropping-thread-local/latest/dropping-thread-local/struct.DroppingThreadLocal.html
[`DroppingThreadLocal::snapshot_iter`]: https://docs.rs/dropping-thread-local/latest/dropping-thread-local/struct.DroppingThreadLocal.html#method.snapshot_iter
[`Arc::clone`]: https://doc.rust-lang.org/std/sync/struct.Arc.html#method.clone

## Prior Art
- [`per-thread-object`](https://github.com/quininer/per-thread-object) - I have not investigated this, but it appears very similar. By the maintainer of `io_uring`.
- [`thread_local`](https://github.com/Amanieu/thread_local-rs) - Discussed in documentation.
- [`std::thread::LocalKey`](https://doc.rust-lang.org/std/thread/struct.LocalKey.html) - Part of the stdlib. It is the abstraction upon which this crate is based.
   - The unstable [`#[thread_local]` attribute](https://github.com/rust-lang/rust/issues/29594) may be faster than a `LocalKey`

## License
Licensed under either the [Apache 2.0 License](./LICENSE-APACHE.txt) or [MIT License](./LICENSE-MIT.txt) at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.