spin-rs

by mvdnes

mvdnes / spin-rs

Spin-based synchronization primitives

148 Stars 46 Forks Last release: Not found MIT License 249 Commits 0 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

spin-rs

Crates.io version docs.rs Build Status

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
    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 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 lock will be unlocked.
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..10 {
            *counter.lock() += 1;
        }
    }
});

for _ in 0..10 {
    *counter.lock() += 1;
}

thread.join().unwrap();

assert_eq!(*counter.lock(), 20);

}

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.