lock_freedom/
lib.rs

1#![cfg_attr(not(feature = "std"), no_std)]
2#![warn(missing_docs)]
3//! A crate providing lock-free data structures and a solution for the "ABA
4//! problem" related to pointers.
5//!
6//! The incinerator is the API which tries to solve the "ABA problem" when
7//! related to pointer dropping. With incinerator, every thread has a local
8//! garbage list. Dropping a shared object consist of first removing the pointer
9//! from the shared context, then adding the pointer to the garbage list.
10//! A "pause counter" is checked. If the counter is zero, then the whole list
11//! is deleted, otherwise, the list will only be deleted later.
12//!
13//! This counter is counting how many times the incinerator was asked to
14//! "pause". A thread may pause the incinerator to load and use the shared
15//! pointer, and this is why it is important to remove the pointer from the
16//! shared context before deleting. Previous version of lockfree used a global
17//! incinerator. Currently, a per-object incinerator is used.
18//!
19//! This crate is under development, and there are plans for some structures.
20//! We have:
21//! - `[x]` [Per-Object Thread-Local Storage](tls::ThreadLocal)
22//! - `[x]` [Channels (SPSC, MPSC, SPMC, MPMC)](channel)
23//! - `[x]` [Map](map::Map)
24//! - `[x]` [Set](set::Set)
25//! - `[x]` [Stack](stack::Stack)
26//! - `[x]` [Queue](queue::Queue)
27//! - `[ ]` Deque
28//!
29//! # Performance Guide
30//! In order to achieve a better time performance with lockfree, it is
31//! recommended to avoid global locking stuff like heap allocation.
32
33extern crate alloc;
34extern crate owned_alloc;
35
36/// Provides convenient re-exports.
37pub mod prelude;
38
39/// Incinerator API. The purpouse of this module is to solve the "ABA problem"
40/// related to pointers while still being lock-free. See documentation of the
41/// inner type for more details.
42#[macro_use]
43#[cfg(feature = "std")]
44pub mod incin;
45
46/// A wait-free per-object Thread Local Storage (TLS).
47#[cfg(feature = "std")]
48pub mod tls;
49
50/// A lock-free queue.
51#[cfg(feature = "std")]
52pub mod queue;
53
54/// A lock-free stack.
55#[cfg(feature = "std")]
56pub mod stack;
57
58/// A lock-free map.
59#[cfg(feature = "std")]
60pub mod map;
61
62/// A lock-free set.
63#[cfg(feature = "std")]
64pub mod set;
65
66/// Collection of lock-free FIFO channels. These channels are fully asynchronous
67/// and their receivers do not provide any sort of `wait-for-message` operation.
68/// It would be blocking otherwise, thus not lock-free. If you need such a
69/// mechanism, consider using this channel with a
70/// [`Condvar`](std::sync::Condvar) or using things like
71/// [`thread::park`](std::thread::park) (not lock-free).
72#[cfg(feature = "std")]
73pub mod channel;
74
75/// A shared removable value. No extra allocation is necessary.
76pub mod removable;
77
78#[allow(dead_code)]
79mod ptr;
lock_freedom/lib.rs

lock_freedom/
lib.rs
