tag | 7d703e90ca185dcd49f4910b9422b44944846463 | |
---|---|---|
tagger | The Android Open Source Project <initial-contribution@android.com> | Tue May 14 16:43:44 2024 -0700 |
object | ccda06839a65b1f58b69fe7184ca9cdf28007e5a |
Android 14.0.0 release 42
commit | ccda06839a65b1f58b69fe7184ca9cdf28007e5a | [log] [tgz] |
---|---|---|
author | Jeff Vander Stoep <jeffv@google.com> | Mon Apr 03 11:09:47 2023 +0000 |
committer | Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com> | Mon Apr 03 11:09:47 2023 +0000 |
tree | 30fab8e942b35661e92e0f597cb0da429f72430d | |
parent | 85ed5a3c590da0b1278b557121dfe794589a8ced [diff] | |
parent | d2677e11395fe3b4f2d663d30bdc3527e5e00ec7 [diff] |
Upgrade spin to 0.9.7 am: 41784ae907 am: 43cce3c0a6 am: dc1efd1c28 am: d2677e1139 Original change: https://android-review.googlesource.com/c/platform/external/rust/crates/spin/+/2519358 Change-Id: I77d13484a99634eeaa3430772cd195cb0011084a Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
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.
Mutex
, RwLock
, Once
, Lazy
and Barrier
equivalentsno_std
environmentslock_api
compatibilityRwLock
guardsInclude the following under the [dependencies]
section in your Cargo.toml
file.
spin = "x.y"
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); }
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.
portable_atomic
enables usage of the portable-atomic
crate to support platforms without native atomic operations (Cortex-M0, etc.). The portable_atomic_unsafe_assume_single_core
cfg or critical-section
feature of portable-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 the portable-atomic
crate for more information.
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:
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 = [...] }
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.
spin
is distributed under the MIT License, (See LICENSE
).