aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorJoel Galenson <jgalenson@google.com>2021-06-22 10:44:01 -0700
committerJoel Galenson <jgalenson@google.com>2021-06-22 10:52:27 -0700
commit8d7807f31efd99bac633112ef2cae12957951c83 (patch)
treee0081d3283ccff4f0a1eee2647b26426554418b2 /README.md
parent538c631506912f7ac70878d9a6731a74a5081a9c (diff)
downloadspin-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.md47
1 files changed, 36 insertions, 11 deletions
diff --git a/README.md b/README.md
index 43a91dd..3d7d758 100644
--- a/README.md
+++ b/README.md
@@ -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