vasi_sync/lib.rs
1//! VirtualAddressSpaceIndependent synchronization primitives.
2//!
3//! This is a collection of synchronization primitives intended for use in
4//! shared memory, which may be mapped into different processes, potentially at
5//! different virtual addresses - see the [`vasi::VirtualAddressSpaceIndependent`]
6//! trait for details.
7//!
8//! In contrast, the synchronization primitives in the `std` crate may or may
9//! not work in this scenario; they are intended primarily to synchronize
10//! threads within a single virtual address space. e.g. they may use `Box`
11//! internally.
12//!
13//! This module contains tests that are designed to work with [loom]. See
14//! [loom] documentation for full details, but a basic way to run these under
15//! loom, from the shadow source directory is:
16//!
17//! ```shell
18//! LOOM_MAX_PREEMPTIONS=3 \
19//! RUSTFLAGS="--cfg loom" \
20//! cargo test \
21//! --manifest-path=src/Cargo.toml \
22//! -p vasi-sync \
23//! --target-dir=loomtarget \
24//! -- --nocapture
25//! ```
26//!
27//! Setting `--target-dir` avoids thrashing the build cache back and forth
28//! between a loom build or not.
29//!
30//! In case of failure, see the loom documentation for guidance on debugging.
31//! In particular LOOM_LOG=trace and/or LOOM_LOCATIONS=1 are a good place to start.
32//!
33//! [loom]: <https://docs.rs/loom/latest/loom/>
34
35// https://github.com/rust-lang/rfcs/blob/master/text/2585-unsafe-block-in-unsafe-fn.md
36#![deny(unsafe_op_in_unsafe_fn)]
37// no_std except when testing.
38// https://github.com/shadow/shadow/issues/2919
39#![cfg_attr(all(not(test), not(loom)), no_std)]
40
41pub mod atomic_tls_map;
42pub mod lazy_lock;
43pub mod scchannel;
44pub mod scmutex;
45
46/// This is public primarily for the integration tests in `tests/*`, which is the
47/// recommended way of writing loom tests.
48///
49/// Not actually intended for usage by other crates.
50pub mod sync;