# Simple Lock
Current Release: 0.4.1
[](https://choosealicense.com/licenses/mit/)
[](https://sr.ht/~dstar4138/simplelock)
[](https://crates.io/crates/simplelock)
[](https://docs.rs/simplelock)
A simple locking abstraction for inter-process/thread synchronization in rust.
### Features:
By default, no features will be enabled and only the [Lock][doc-lock]
trait and utility functionality will be available. This can be useful
if you wish to hand-roll your own Lock, but don't want to re-write the
utility functions.
Current implementations:
* `fake` - Enables the FakeLock implementation (only useful for testing).
* `file` - Enables the FileLock implementation (most common and cross-platform).
* `sema` - Enables the SemaphoreLock implementation (minimal, libc/nix only).
### Examples:
A basic example
```rust
use simplelock::*;
// Our application's lock namespace. We use this on creation to allow for
// cross-process synchronization. This lets multiple instances of this
// application run at once without conflicting.
const MY_APP_NAME: &str = "my_app_name";
fn main() -> SimpleLockResult<()> {
// Creates the lock based on the "feature" enabled in Cargo.toml.
// Will return a SimpleLockError if an error happens when creating
// the lock with the default configuration, or if no lock type was
// enabled as a "feature".
let mut lock = default_lock(MY_APP_NAME)?;
// One of the utility functions provided, simple critical-section
// locking. All of the bundled Locks' behaviours, will, by default,
// hang until the lock is available. This can be customized.
let result = lock_until_finished(
&mut lock,
|| {
/// Some critical code.
})?;
// ... Do something with the result.
}
```
If you needed more customization of a lock's behaviour, you may use the
[LockBuilder][doc-lockbuilder] to override lock/unlock behaviour.
```rust
use simplelock::*;
fn main() -> SimpleLockResult<()> {
let mut lock = LockBuilder::default()
.with_try_lock() // Allow immediate return if lock taken.
.with_silent_unlock() // Suppress failure to return result.
.build(MY_APP_NAME)?;
// do something with your lock.
}
```
If you wanted to implement your own lock, you can implement the
[Lock][doc-lock] trait or [ConcreteLock][doc-concretelock] and
use it with all the same utility functionality provided by this
package. If you do not enable any features, this package is only
the trait and utility functions.
### Caveats:
If you are ok with the below, then go ahead and use this package.
* `unsafe` - The "semaphore" lock implementation has unsafe code,
this is because the [nix][cargo-nix] package does not have
implementations for POSIX semaphores yet. If this is unacceptable,
don't enable the "semaphore" feature.
* `no_std` - We currently do not have any non-stdlib available lock
implementations ("semaphore" is close). Some utility functionality
uses `std` but some rework before v1.0 is needed before then.
### Contributing:
Please see [doc/CONTRIBUTING.md][doc-contrib].
### FAQ:
Please see [doc/FAQ.md][doc-faq].
[cargo-nix]: https://crates.io/crates/nix
[doc-lock]: https://docs.rs/simplelock/latest/simplelock/trait.Lock.html
[doc-concretelock]: https://docs.rs/simplelock/latest/simplelock/trait.ConcreteLock.html
[doc-lockbuilder]: https://docs.rs/simplelock/latest/simplelock/struct.LockBuilder.html
[doc-contrib]: https://git.sr.ht/~dstar4138/simplelock/tree/master/doc/CONTRIBUTING.md
[doc-faq]: https://git.sr.ht/~dstar4138/simplelock/tree/master/doc/FAQ.md