# Simple Lock

Current Release: 0.4.1

[![License](https://img.shields.io/crates/l/simplelock.svg)](https://choosealicense.com/licenses/mit/)
[![builds.sr.ht status](https://builds.sr.ht/~dstar4138/simplelock.svg)](https://sr.ht/~dstar4138/simplelock)
[![Latest version](https://img.shields.io/crates/v/simplelock.svg)](https://crates.io/crates/simplelock)
[![Documentation](https://docs.rs/simplelock/badge.svg)](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