spin-rs

Spin-based synchronisation primitives.

This crate implements a variety of simple spinlock-like primitives with similar interfaces to those in std::sync. Because synchronisation uses spinning, the primitives are suitable for use in no_std environments.

Before deciding to use spin, we recommend reading this superb blog post by @matklad that discusses the pros and cons of spinlocks. If you have access to std, it's likely that the primitives in std::sync will serve you better except in very specific circumstances.

Features

• Mutex, RwLock and Once equivalents.
• Support for no_std environments
• lock_api compatibility
• Upgradeable RwLock guards
• Guards can be sent and shared between threads
• Guard leaking

Usage

Include the following code in your Cargo.toml

toml [dependencies.spin] version = "0.5"

Example

When calling lock on a Mutex you will get a guard value that allows referencing the data. When this guard is dropped, the lock will be unlocked.

```rust extern crate spin;

fn main() { let mutex = spin::Mutex::new(0); let rw_lock = spin::RwLock::new(0);

// Modify the data
{
  let mut data = mutex.lock();
  *data = 2;
  let mut data = rw_lock.write();
  *data = 3;
}

// Read the data
let answer = {
  let data1 = mutex.lock();
  let data2 = rw_lock.read();
  let data3 = rw_lock.read(); // sharing
  (*data1, *data2, *data3)
};

println!("Answers are {:?}", answer);

} ```

Remarks

It is often desirable to have a lock shared between threads. Wrapping the lock in an std::sync::Arc is route through which this might be achieved.

Locks provide zero-overhead access to their data when accessed through a mutable reference by using their get_mut methods.

The behaviour of these lock is similar to their namesakes in std::sync. they differ on the following:

• Locks will not be poisoned in case of failure.
• Threads will not yield to the OS scheduler when encounter a lock that cannot be accessed. Instead, they will 'spin' in a busy loop until the lock becomes available.

License

spin is distributed under the Apache License, Version 2.0, (See LICENSE or https://www.apache.org/licenses/LICENSE-2.0).