# Flexible Locks
This crate aims at providing generic, flexible implementations of locking
primitives. For now, it only provides `Mutex` types (i.e. no `RwLock`, etc.),
without [poisoning], and without `try_lock`. Support for those can be
added in the future if there is interest (patches welcome). Poisoning is not
necessary with panic=abort.
[poisoning]: https://doc.rust-lang.org/std/sync/struct.Mutex.html#poisoning
The provided types allow flexibility in layout and locking implementation.
## Differences from `std::sync::Mutex`
- No poisoning.
- No `try_lock`.
- The underlying raw mutex primitive can be of any kind, within a `Box` or
not, as long as the `RawMutex` trait is implemented. Choose carefully.
- The raw mutex primitive can be embedded anywhere in the data type. See the
`MutexWrap` type for a variant that looks more like `std::sync::Mutex`,
but still allows to use a specific raw mutex primitive.
- With care, this can allow to share data through FFI and contend on the same
locks. See the `ffi-example` directory.
## Examples
```rust
extern crate flexible_locks;
#[macro_use]
extern crate flexible_locks_derive;
use flexible_locks::{Mutex, RawMutex};
// Pick your choice of raw mutex;
#[cfg(windows)]
use flexible_locks::SRWLOCK as RawOsMutex;
#[cfg(unix)]
use flexible_locks::pthread_mutex_t as RawOsMutex;
use std::sync::Arc;
use std::thread;
use std::sync::mpsc::channel;
#[derive(MutexProtected, Default)]
struct Data {
a: usize,
b: usize,
#[mutex]
mutex: RawOsMutex,
}
const N: usize = 10;
fn main() {
// Spawn a few threads to increment a shared variable (non-atomically),
// and let the main thread know once all increments are done.
//
// Here we're using an Arc to share memory among threads, and the data
// inside the Arc is protected with a mutex.
let data = Arc::new(Mutex::new(Data::default()));
let (tx, rx) = channel();
for _ in 0..N {
let (data, tx) = (data.clone(), tx.clone());
thread::spawn(move || {
// The shared state can only be accessed once the lock is held.
// Our non-atomic increment is safe because we're the only thread
// which can access the shared state when the lock is held.
let mut data = data.lock();
data.a += 1;
if data.a == N {
tx.send(()).unwrap();
}
// the lock is unlocked here when `data` goes out of scope.
});
}
rx.recv().unwrap();
}
```
## Features
The `parking_lot` feature can be enabled, providing a `RawMutex`
implementation for `parking_log::Mutex<()>`.
License: Apache-2.0/MIT