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
andOnce
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
[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.
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).