40 releases
0.7.2 | Apr 23, 2024 |
---|---|
0.7.1 | Oct 2, 2023 |
0.7.0 | Aug 4, 2023 |
0.6.1 | Jul 21, 2023 |
0.0.1 | Dec 7, 2018 |
#15 in Concurrency
394,282 downloads per month
Used in 1,005 crates
(137 directly)
270KB
5.5K
SLoC
Loom
Loom is a testing tool for concurrent Rust code. It runs a test many times, permuting the possible concurrent executions of that test under the C11 memory model. It uses state reduction techniques to avoid combinatorial explosion.
Quickstart
The loom documentation has significantly more documentation on
how to use loom. But if you just want a jump-start, first add this to
your Cargo.toml
.
[target.'cfg(loom)'.dependencies]
loom = "0.7"
Next, create a test file and add a test:
use loom::sync::Arc;
use loom::sync::atomic::AtomicUsize;
use loom::sync::atomic::Ordering::{Acquire, Release, Relaxed};
use loom::thread;
#[test]
#[should_panic]
fn buggy_concurrent_inc() {
loom::model(|| {
let num = Arc::new(AtomicUsize::new(0));
let ths: Vec<_> = (0..2)
.map(|_| {
let num = num.clone();
thread::spawn(move || {
let curr = num.load(Acquire);
num.store(curr + 1, Release);
})
})
.collect();
for th in ths {
th.join().unwrap();
}
assert_eq!(2, num.load(Relaxed));
});
}
Then, run the test with
RUSTFLAGS="--cfg loom" cargo test --test buggy_concurrent_inc --release
Unsupported features
Loom currently does not implement the full C11 memory model. Here is the (incomplete) list of unsupported features.
SeqCst
accesses (e.g.load
,store
, ..): They are are regarded asAcqRel
. That is, they impose weaker synchronization, causing Loom to generate false alarms (not complete). See #180 for example. On the other hand,fence(SeqCst)
is supported.- Load buffering behavior:
Loom does not explore some executions that are possible in the C11 memory
model. That is, there can be a bug in the checked code even if Loom says
there is no bug (not sound). See the
load_buffering
test case intests/litmus.rs
.
License
This project is licensed under the MIT license.
Contribution
Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in loom
by you, shall be licensed as MIT,
without any additional terms or conditions.
Dependencies
~4–29MB
~412K SLoC