diff options
author | Joel Galenson <jgalenson@google.com> | 2021-06-22 10:44:01 -0700 |
---|---|---|
committer | Joel Galenson <jgalenson@google.com> | 2021-06-22 10:52:27 -0700 |
commit | 8d7807f31efd99bac633112ef2cae12957951c83 (patch) | |
tree | e0081d3283ccff4f0a1eee2647b26426554418b2 /README.md | |
parent | 538c631506912f7ac70878d9a6731a74a5081a9c (diff) | |
download | spin-8d7807f31efd99bac633112ef2cae12957951c83.tar.gz |
Upgrade rust/crates/spin to 0.9.1
Test: Build this and its dependent library
Change-Id: I102cd942806f3b7b73ea1c3d54c5f5cca0292ed4
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 47 |
1 files changed, 36 insertions, 11 deletions
@@ -18,14 +18,14 @@ spinlocks. If you have access to `std`, it's likely that the primitives in ## Features -- `Mutex`, `RwLock` and `Once` equivalents +- `Mutex`, `RwLock`, `Once`, `Lazy` and `Barrier` equivalents - Support for `no_std` environments - [`lock_api`](https://crates.io/crates/lock_api) compatibility - Upgradeable `RwLock` guards - Guards can be sent and shared between threads - Guard leaking -- `std` feature to enable yield to the OS scheduler in busy loops -- `Mutex` can become a ticket lock +- Ticket locks +- Different strategies for dealing with contention ## Usage @@ -38,7 +38,7 @@ 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. +to the data. When this guard is dropped, the mutex will become available again. ```rust extern crate spin; @@ -50,19 +50,19 @@ fn main() { let thread = thread::spawn({ let counter = counter.clone(); move || { - for _ in 0..10 { + for _ in 0..100 { *counter.lock() += 1; } } }); - for _ in 0..10 { + for _ in 0..100 { *counter.lock() += 1; } thread.join().unwrap(); - assert_eq!(*counter.lock(), 20); + assert_eq!(*counter.lock(), 200); } ``` @@ -70,11 +70,27 @@ fn main() { The crate comes with a few feature flags that you may wish to use. -- `lock_api` enabled support for [`lock_api`](https://crates.io/crates/lock_api) +- `mutex` enables the `Mutex` type. -- `ticket_mutex` uses a ticket lock for the implementation of `Mutex` +- `spin_mutex` enables the `SpinMutex` type. -- `std` enables support for thread yielding instead of spinning +- `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`](https://crates.io/crates/lock_api) + +- `std` enables support for thread yielding instead of spinning. ## Remarks @@ -89,7 +105,16 @@ 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. + 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 |