Crate distributed_lock

Expand description

Distributed locks for Rust with multiple backend support.

This crate provides distributed synchronization primitives (mutex locks, reader-writer locks, semaphores) that work across processes and machines. Multiple backend implementations are available: PostgreSQL, Redis, and file system.

§Quick Start

use distributed_lock::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a provider (example: file backend)
    let provider = FileLockProvider::builder()
        .build("/tmp/locks")?;

    // Create a lock by name
    let lock = provider.create_lock("my-resource");

    // Acquire the lock with a timeout
    let handle = lock.acquire(Some(Duration::from_secs(5))).await?;

    // Critical section - we have exclusive access
    println!("Doing critical work...");

    // Release the lock (also happens automatically on drop)
    handle.release().await?;

    Ok(())
}

§Backends

§File System Backend

Uses OS-level file locking. Simple and requires no external services.

use distributed_lock::FileLockProvider;

let provider = FileLockProvider::builder()
    .build("/tmp/locks")?;

§PostgreSQL Backend

Uses PostgreSQL advisory locks. Production-ready with connection pooling.

use distributed_lock::PostgresLockProvider;

let provider = PostgresLockProvider::builder()
    .connection_string("postgresql://user:pass@localhost/db")
    .build()
    .await?;

§Redis Backend

Uses Redis with RedLock algorithm for multi-server deployments. Supports semaphores and automatic lease extension.

use distributed_lock::RedisLockProvider;

let provider = RedisLockProvider::builder()
    .add_server("redis://localhost:6379")
    .build()
    .await?;

§Features

Exclusive Locks: Mutual exclusion across processes
Reader-Writer Locks: Multiple readers or single writer
Semaphores: Limit concurrent access to N processes
Async/Await: Full async support with tokio
Backend Agnostic: Swap backends without changing application code
Handle Loss Detection: Detect when locks are lost due to connection issues

§Crate Organization

This is a meta-crate that re-exports types from:

distributed-lock-core: Core traits and types
distributed-lock-file: File system backend
distributed-lock-postgres: PostgreSQL backend
distributed-lock-redis: Redis backend

For fine-grained control, you can depend on individual crates instead.

Modules§

connection: Connection pool management for PostgreSQL locks.
error: Error types for distributed lock operations.
key: PostgreSQL advisory lock key encoding.
name: File name validation and conversion utilities.
prelude: Convenience prelude for distributed lock types.
redlock: RedLock algorithm implementation for distributed locking across multiple Redis servers.
semaphore: Redis distributed semaphore implementation.
timeout: Timeout value helpers.
traits: Core traits for distributed locks.

Structs§

FileDistributedLock: A file-based distributed lock.
FileLockHandle: Handle for a held file lock.
FileLockProvider: Provider for file-based distributed locks.
FileLockProviderBuilder: Builder for file-based lock provider configuration.
PostgresDistributedReaderWriterLock: A PostgreSQL-based distributed reader-writer lock.
PostgresLockProvider: Provider for PostgreSQL-based distributed locks.
PostgresLockProviderBuilder: Builder for PostgreSQL lock provider configuration.
PostgresReadLockHandle: Handle for a held PostgreSQL read lock.
PostgresWriteLockHandle: Handle for a held PostgreSQL write lock.
RedisDistributedLock: A Redis-based distributed lock.
RedisDistributedReaderWriterLock: A Redis-based distributed reader-writer lock.
RedisDistributedSemaphore: A Redis-based distributed semaphore.
RedisLockHandle: Handle for a held Redis lock.
RedisLockProvider: Provider for Redis-based distributed locks.
RedisLockProviderBuilder: Builder for Redis lock provider configuration.
RedisReadLockHandle: Handle for a held Redis read lock.
RedisSemaphoreHandle: Handle for a held semaphore ticket.
RedisWriteLockHandle: Handle for a held Redis write lock.

Enums§

LockError: Errors that can occur during lock operations.
PostgresAdvisoryLockKey: Key for PostgreSQL advisory locks.

Traits§

DistributedLock: A distributed mutual exclusion lock.
DistributedReaderWriterLock: A distributed reader-writer lock.
DistributedSemaphore: A distributed counting semaphore.
LockHandle: Handle to a held distributed lock.
LockProvider: Factory for creating distributed locks by name.
LockProviderExt: Extension trait providing convenience methods for lock providers.
ReaderWriterLockProvider: Factory for creating reader-writer locks by name.
SemaphoreProvider: Factory for creating semaphores by name.

Type Aliases§

LockResult: Result type for lock operations.