arc_swap/docs/
limitations.rs

1//! Limitations and common pitfalls.
2//!
3//! # Sized types
4//!
5//! This currently works only for `Sized` types. Unsized types have „fat pointers“, which are twice
6//! as large as the normal ones. The [`AtomicPtr`] doesn't support them. One could use something
7//! like `AtomicU128` for them. The catch is this doesn't exist and the difference would make it
8//! really hard to implement the debt storage/stripped down hazard pointers.
9//!
10//! A workaround is to use double indirection:
11//!
12//! ```rust
13//! # use arc_swap::ArcSwap;
14//! // This doesn't work:
15//! // let data: ArcSwap<[u8]> = ArcSwap::new(Arc::from([1, 2, 3]));
16//!
17//! // But this does:
18//! let data: ArcSwap<Box<[u8]>> = ArcSwap::from_pointee(Box::new([1, 2, 3]));
19//! # drop(data);
20//! ```
21//!
22//! It also may be possible to use `ArcSwap` with the [`triomphe::ThinArc`] (that crate needs
23//! enabling a feature flag to cooperate with `ArcSwap`).
24//!
25//! # Too many [`Guard`]s
26//!
27//! There's only limited number of "fast" slots for borrowing from [`ArcSwap`] for each single
28//! thread (currently 8, but this might change in future versions). If these run out, the algorithm
29//! falls back to slower path.
30//!
31//! If too many [`Guard`]s are kept around, the performance might be poor. These are not intended
32//! to be stored in data structures or used across async yield points.
33//!
34//! [`ArcSwap`]: crate::ArcSwap
35//! [`Guard`]: crate::Guard
36//! [`AtomicPtr`]: std::sync::atomic::AtomicPtr
37//!
38//! # No `Clone` implementation
39//!
40//! Previous version implemented [`Clone`], but it turned out to be very confusing to people, since
41//! it created fully independent [`ArcSwap`]. Users expected the instances to be tied to each
42//! other, that store in one would change the result of future load of the other.
43//!
44//! To emulate the original behaviour, one can do something like this:
45//!
46//! ```rust
47//! # use arc_swap::ArcSwap;
48//! # let old = ArcSwap::from_pointee(42);
49//! let new = ArcSwap::new(old.load_full());
50//! # let _ = new;
51//! ```
52//!
53//! [`triomphe::ThinArc`]: https://docs.rs/triomphe/latest/triomphe/struct.ThinArc.html
arc_swap/docs/limitations.rs

arc_swap/docs/
limitations.rs
