distributed_lock/lib.rs
1//! Distributed locks for Rust with multiple backend support.
2//!
3//! This crate provides distributed synchronization primitives (mutex locks,
4//! reader-writer locks, semaphores) that work across processes and machines.
5//! Multiple backend implementations are available: PostgreSQL, Redis, and file system.
6//!
7//! # Quick Start
8//!
9//! ```rust,no_run
10//! use distributed_lock::*;
11//! use std::time::Duration;
12//!
13//! #[tokio::main]
14//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
15//! // Create a provider (example: file backend)
16//! let provider = FileLockProvider::builder()
17//! .build("/tmp/locks")?;
18//!
19//! // Create a lock by name
20//! let lock = provider.create_lock("my-resource");
21//!
22//! // Acquire the lock with a timeout
23//! let handle = lock.acquire(Some(Duration::from_secs(5))).await?;
24//!
25//! // Critical section - we have exclusive access
26//! println!("Doing critical work...");
27//!
28//! // Release the lock (also happens automatically on drop)
29//! handle.release().await?;
30//!
31//! Ok(())
32//! }
33//! ```
34//!
35//! # Backends
36//!
37//! ## File System Backend
38//!
39//! Uses OS-level file locking. Simple and requires no external services.
40//!
41//! ```rust,no_run
42//! use distributed_lock::FileLockProvider;
43//!
44//! let provider = FileLockProvider::builder()
45//! .build("/tmp/locks")?;
46//! ```
47//!
48//! ## PostgreSQL Backend
49//!
50//! Uses PostgreSQL advisory locks. Production-ready with connection pooling.
51//!
52//! ```rust,no_run
53//! use distributed_lock::PostgresLockProvider;
54//!
55//! let provider = PostgresLockProvider::builder()
56//! .connection_string("postgresql://user:pass@localhost/db")
57//! .build()
58//! .await?;
59//! ```
60//!
61//! ## Redis Backend
62//!
63//! Uses Redis with RedLock algorithm for multi-server deployments. Supports
64//! semaphores and automatic lease extension.
65//!
66//! ```rust,no_run
67//! use distributed_lock::RedisLockProvider;
68//!
69//! let provider = RedisLockProvider::builder()
70//! .add_server("redis://localhost:6379")
71//! .build()
72//! .await?;
73//! ```
74//!
75//! # Features
76//!
77//! - **Exclusive Locks**: Mutual exclusion across processes
78//! - **Reader-Writer Locks**: Multiple readers or single writer
79//! - **Semaphores**: Limit concurrent access to N processes
80//! - **Async/Await**: Full async support with tokio
81//! - **Backend Agnostic**: Swap backends without changing application code
82//! - **Handle Loss Detection**: Detect when locks are lost due to connection issues
83//!
84//! # Crate Organization
85//!
86//! This is a meta-crate that re-exports types from:
87//! - `distributed-lock-core`: Core traits and types
88//! - `distributed-lock-file`: File system backend
89//! - `distributed-lock-postgres`: PostgreSQL backend
90//! - `distributed-lock-redis`: Redis backend
91//!
92//! For fine-grained control, you can depend on individual crates instead.
93
94// Re-export core types and traits
95pub use distributed_lock_core::*;
96
97// Re-export file backend
98#[allow(ambiguous_glob_reexports)]
99pub use distributed_lock_file::*;
100
101// Re-export postgres backend
102#[allow(ambiguous_glob_reexports)]
103pub use distributed_lock_postgres::*;
104
105// Re-export redis backend
106#[allow(ambiguous_glob_reexports)]
107pub use distributed_lock_redis::*;