Awesome
spin-rs
Spin-based synchronization primitives.
This crate provides spin-based
versions of the primitives in std::sync
. Because synchronization is done
through 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
,Once
,Lazy
andBarrier
equivalents- Support for
no_std
environments lock_api
compatibility- Upgradeable
RwLock
guards - Guards can be sent and shared between threads
- Guard leaking
- Ticket locks
- Different strategies for dealing with contention
Usage
Include the following under the [dependencies]
section in your Cargo.toml
file.
spin = "x.y"
Example
When calling lock
on a Mutex
you will get a guard value that provides access
to the data. When this guard is dropped, the mutex will become available again.
extern crate spin;
use std::{sync::Arc, thread};
fn main() {
let counter = Arc::new(spin::Mutex::new(0));
let thread = thread::spawn({
let counter = counter.clone();
move || {
for _ in 0..100 {
*counter.lock() += 1;
}
}
});
for _ in 0..100 {
*counter.lock() += 1;
}
thread.join().unwrap();
assert_eq!(*counter.lock(), 200);
}
Feature flags
The crate comes with a few feature flags that you may wish to use.
-
mutex
enables theMutex
type. -
spin_mutex
enables theSpinMutex
type. -
ticket_mutex
enables theTicketMutex
type. -
use_ticket_mutex
switches to a ticket lock for the implementation ofMutex
. This is recommended only on targets for which ordinary spinning locks perform very badly because it will change the implementation used by other crates that depend onspin
. -
rwlock
enables theRwLock
type. -
once
enables theOnce
type. -
lazy
enables theLazy
type. -
barrier
enables theBarrier
type. -
lock_api
enables support forlock_api
-
std
enables support for thread yielding instead of spinning. -
portable_atomic
enables usage of theportable-atomic
crate to support platforms without native atomic operations (Cortex-M0, etc.). Theportable_atomic_unsafe_assume_single_core
cfg orcritical-section
feature ofportable-atomic
crate must also be set by the final binary crate.When using the cfg, this can be done by adapting the following snippet to the
.cargo/config
file:[target.<target>] rustflags = [ "--cfg", "portable_atomic_unsafe_assume_single_core" ]
Note that this cfg is unsafe by nature, and enabling it for multicore systems is unsound.
When using the
critical-section
feature, you need to implement the critical-section implementation that sound for your system by implementing an unsafe trait. See the documentation for theportable-atomic
crate for more information.
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.
Many of the feature flags listed above are enabled by default. If you're writing a library, we recommend disabling those that you don't use to avoid increasing compilation time for your crate's users. You can do this like so:
[dependencies]
spin = { version = "x.y", default-features = false, features = [...] }
Minimum Safe Rust Version (MSRV)
This crate is guaranteed to compile on a Minimum Safe Rust Version (MSRV) of 1.38.0 and above. This version will not be changed without a minor version bump.
License
spin
is distributed under the MIT License, (See LICENSE
).