commit	710e4632fdcf967e135fad7f314e80fbf8864946	[log] [tgz]
author	Joel Galenson <jgalenson@google.com>	Mon Nov 29 14:05:28 2021 -0800
committer	Joel Galenson <jgalenson@google.com>	Fri Dec 10 15:33:31 2021 -0800
tree	e61086a0232b4ab7bcda37880bdc1ad1aa20fb33
parent	4a361056b118e83b1f6930ed986ba235127b404d [diff]

tree: e61086a0232b4ab7bcda37880bdc1ad1aa20fb33

README.md

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