Need help with spin-rs?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

mvdnes
184 Stars 54 Forks MIT License 292 Commits 6 Opened issues

Description

Spin-based synchronization primitives

Services available

!
?

Need anything else?

Contributors list

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
    ,
    Once
    ,
    Lazy
    and
    Barrier
    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 the
    Mutex
    type.
  • spin_mutex
    enables the
    SpinMutex
    type.
  • ticket_mutex
    enables the
    TicketMutex
    type.
  • use_ticket_mutex
    switches to a ticket lock for the implementation of
    Mutex
    . 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 on
    spin
    .
  • rwlock
    enables the
    RwLock
    type.
  • once
    enables the
    Once
    type.
  • lazy
    enables the
    Lazy
    type.
  • barrier
    enables the
    Barrier
    type.
  • lock_api
    enables support for
    lock_api
  • std
    enables support for thread yielding instead of spinning.

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 = [...] }

License

spin
is distributed under the MIT License, (See
LICENSE
).

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.