https://github.com/tokio-rs/loom

Concurrency permutation testing tool for Rust.
https://github.com/tokio-rs/loom

Last synced: 3 days ago
JSON representation

Concurrency permutation testing tool for Rust.

• Host: GitHub
• URL: https://github.com/tokio-rs/loom
• Owner: tokio-rs
• License: mit
• Created: 2018-12-15T06:11:47.000Z (almost 6 years ago)
• Default Branch: master
• Last Pushed: 2024-09-15T13:57:28.000Z (3 months ago)
• Last Synced: 2024-10-29T15:04:47.027Z (about 1 month ago)
• Language: Rust
• Homepage:
• Size: 526 KB
• Stars: 2,127
• Watchers: 32
• Forks: 110
• Open Issues: 96
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-rust-formalized-reasoning - Loom - concurrency permutation testing tool for Rust. (Projects / Verification)
• awesome-code-for-gamedev - loom - a testing tool for concurrent Rust code. (Testing / Concurrent)
• dynamic-analysis - loom

README

        
# 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][spec]. It uses [state reduction

techniques][cdschecker] to avoid combinatorial explosion.

[![Crates.io](https://img.shields.io/crates/v/loom.svg)](https://crates.io/crates/loom)

[![Documentation](https://docs.rs/loom/badge.svg)][docs]

[![Build Status](https://github.com/tokio-rs/loom/actions/workflows/ci.yml/badge.svg)](https://github.com/tokio-rs/loom/actions)

[![Discord chat](https://img.shields.io/discord/500028886025895936.svg?logo=discord&style=flat-square)](https://discord.com/channels/500028886025895936/628283088555737089)

[docs]: https://docs.rs/loom

[spec]: https://en.cppreference.com/w/cpp/atomic/memory_order

[cdschecker]: http://plrg.eecs.uci.edu/publications/toplas16.pdf

## Quickstart

The [loom documentation][docs] has significantly more documentation on

how to use loom. But if you just want a jump-start, first add this to

your `Cargo.toml`.

```toml

[target.'cfg(loom)'.dependencies]

loom = "0.7"

```

Next, create a test file and add a test:

```rust

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

```console

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 regarded as `AcqRel`. That is, they impose weaker

  synchronization, causing Loom to generate false alarms (not complete). See

  [#180](https://github.com/tokio-rs/loom/issues/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 in

  `tests/litmus.rs`.

## License

This project is licensed under the [MIT license](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.