Crate simplelock

SimpleLock is a set of utility functions and a simple Lock trait, which can be used for inter-process synchronization. This differs from many of the other “lock” packages in that it works cross-process using OS/FS/etc mechanisms.

We hope to expand and bundle a number of verified implementations with it, but in the spirit of Rust’s “only pay for what you use”, they will be gated behind feature flags or enclosed in separate packages.

For example, you can use the FileLock implementation by adding this to your Cargo.toml:

[dependencies]
simplelock = { version = "*", features = [ "file" ] }

Presently we have the following implementations available for use:

• fake - Enables the FakeLock implementation (useful for testing only).
• file - Enables the FileLock implementation (most common and cross-platform).
• sema - Enables the SemaphoreLock implementation (minimal libc/nix only).

Un-implemented mechanisms which may come later:

• smem - Shared Memory.
• Simple distributed locks:
  • http - URL/web-hook based (i.e. RFC 7232).
  • callback - Customizable callback (i.e. redis dist-lock, etc).

Please request others or hand-roll your own. You need not enable any features and implement the Lock trait directly.

Examples:

use simplelock::*;

fn main() -> SimpleLockResult<()> {
    // Based on the "feature" enabled, this will create the default lock.
    // Will return a SimpleLockError on error, or if no lock type was enabled.
    let mut lock = default_lock("my_app_name")?;

    // One utility function provided, simple critical-section locking.
    let result = lock_until_finished(
        &mut lock,
        || {
            /// Some critical code.
        })?;

    // ... Do something with the result.
}

Structs

FakeLock

A dummy lock which is actually just a boolean flag. This is used to test the functionality of higher level functionality where locks would have been useful.

FileLock

A simple cross-platform file lock.

LockBuilder

Builds a lock from a ConcreteLock implementation using the configurations enabled. See below for all possible configurations. Note, by implementing the ConcreteLock implementation you can wrap it with a LockBuilder to create the Lock interface used in all utility functions.

SemaphoreLock

A safe publicly usable object surrounding the wrapper we built since ‘nix’ doesn’t have it yet.

Enums

LockStatus

Possible status a Lock can have.

SimpleLockError

SimpleLock’s Error type.

Traits

ConcreteLock

A full implementation of a Lock which can handle all LockBuilder configurations.

Lock

The Simple Lock trait.

Functions

default_lock

Get a lock with default configuration based on the feature enabled.

lock_until_finished

Simple utility function for wrapping a closure with a lock.

Type Aliases

SimpleLockResult

SimpleLock’s Result value override to inject our Error type.