feat: add comprehensive README documentation for all RustFS submodules (#48)

2026-08-20 11:32:19 +00:00 · 2025-07-04 23:02:13 +08:00
parent c41299a29f
commit fa17f7b1e3
20 changed files with 8752 additions and 172 deletions
@@ -0,0 +1,392 @@
+[![RustFS](https://rustfs.com/images/rustfs-github.png)](https://rustfs.com)
+
+# RustFS Lock - Distributed Locking
+
+<p align="center">
+  <strong>Distributed locking and synchronization for RustFS object storage</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/rustfs/rustfs/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/rustfs/rustfs/actions/workflows/ci.yml/badge.svg" /></a>
+  <a href="https://docs.rustfs.com/en/">📖 Documentation</a>
+  · <a href="https://github.com/rustfs/rustfs/issues">🐛 Bug Reports</a>
+  · <a href="https://github.com/rustfs/rustfs/discussions">💬 Discussions</a>
+</p>
+
+---
+
+## 📖 Overview
+
+**RustFS Lock** provides distributed locking and synchronization primitives for the [RustFS](https://rustfs.com) distributed object storage system. It ensures data consistency and prevents race conditions in multi-node environments through various locking mechanisms and coordination protocols.
+
+> **Note:** This is a core submodule of RustFS that provides essential distributed locking capabilities for the distributed object storage system. For the complete RustFS experience, please visit the [main RustFS repository](https://github.com/rustfs/rustfs).
+
+## ✨ Features
+
+### 🔒 Distributed Locking
+
+- **Exclusive Locks**: Mutual exclusion across cluster nodes
+- **Shared Locks**: Reader-writer lock semantics
+- **Timeout Support**: Configurable lock timeouts and expiration
+- **Deadlock Prevention**: Automatic deadlock detection and resolution
+
+### 🔄 Synchronization Primitives
+
+- **Distributed Mutex**: Cross-node mutual exclusion
+- **Distributed Semaphore**: Resource counting across nodes
+- **Distributed Barrier**: Coordination point for multiple nodes
+- **Distributed Condition Variables**: Wait/notify across nodes
+
+### 🛡️ Consistency Guarantees
+
+- **Linearizable Operations**: Strong consistency guarantees
+- **Fault Tolerance**: Automatic recovery from node failures
+- **Network Partition Handling**: CAP theorem aware implementations
+- **Consensus Integration**: Raft-based consensus for critical locks
+
+### 🚀 Performance Features
+
+- **Lock Coalescing**: Efficient batching of lock operations
+- **Adaptive Timeouts**: Dynamic timeout adjustment
+- **Lock Hierarchy**: Hierarchical locking for better scalability
+- **Optimistic Locking**: Reduced contention through optimistic approaches
+
+## 📦 Installation
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+rustfs-lock = "0.1.0"
+```
+
+## 🔧 Usage
+
+### Basic Distributed Lock
+
+```rust
+use rustfs_lock::{DistributedLock, LockManager, LockOptions};
+use std::time::Duration;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create lock manager
+    let lock_manager = LockManager::new("cluster-endpoint").await?;
+
+    // Acquire distributed lock
+    let lock_options = LockOptions {
+        timeout: Duration::from_secs(30),
+        auto_renew: true,
+        ..Default::default()
+    };
+
+    let lock = lock_manager.acquire_lock("resource-key", lock_options).await?;
+
+    // Critical section
+    {
+        println!("Lock acquired, performing critical operations...");
+        // Your critical code here
+        tokio::time::sleep(Duration::from_secs(2)).await;
+    }
+
+    // Release lock
+    lock.release().await?;
+    println!("Lock released");
+
+    Ok(())
+}
+```
+
+### Distributed Mutex
+
+```rust
+use rustfs_lock::{DistributedMutex, LockManager};
+use std::sync::Arc;
+
+async fn distributed_mutex_example() -> Result<(), Box<dyn std::error::Error>> {
+    let lock_manager = Arc::new(LockManager::new("cluster-endpoint").await?);
+
+    // Create distributed mutex
+    let mutex = DistributedMutex::new(lock_manager.clone(), "shared-resource");
+
+    // Spawn multiple tasks
+    let mut handles = vec![];
+
+    for i in 0..5 {
+        let mutex = mutex.clone();
+        let handle = tokio::spawn(async move {
+            let _guard = mutex.lock().await.unwrap();
+            println!("Task {} acquired mutex", i);
+
+            // Simulate work
+            tokio::time::sleep(Duration::from_secs(1)).await;
+
+            println!("Task {} releasing mutex", i);
+            // Guard is automatically released when dropped
+        });
+
+        handles.push(handle);
+    }
+
+    // Wait for all tasks to complete
+    for handle in handles {
+        handle.await?;
+    }
+
+    Ok(())
+}
+```
+
+### Distributed Semaphore
+
+```rust
+use rustfs_lock::{DistributedSemaphore, LockManager};
+use std::sync::Arc;
+
+async fn distributed_semaphore_example() -> Result<(), Box<dyn std::error::Error>> {
+    let lock_manager = Arc::new(LockManager::new("cluster-endpoint").await?);
+
+    // Create distributed semaphore with 3 permits
+    let semaphore = DistributedSemaphore::new(
+        lock_manager.clone(),
+        "resource-pool",
+        3
+    );
+
+    // Spawn multiple tasks
+    let mut handles = vec![];
+
+    for i in 0..10 {
+        let semaphore = semaphore.clone();
+        let handle = tokio::spawn(async move {
+            let _permit = semaphore.acquire().await.unwrap();
+            println!("Task {} acquired permit", i);
+
+            // Simulate work
+            tokio::time::sleep(Duration::from_secs(2)).await;
+
+            println!("Task {} releasing permit", i);
+            // Permit is automatically released when dropped
+        });
+
+        handles.push(handle);
+    }
+
+    // Wait for all tasks to complete
+    for handle in handles {
+        handle.await?;
+    }
+
+    Ok(())
+}
+```
+
+### Distributed Barrier
+
+```rust
+use rustfs_lock::{DistributedBarrier, LockManager};
+use std::sync::Arc;
+
+async fn distributed_barrier_example() -> Result<(), Box<dyn std::error::Error>> {
+    let lock_manager = Arc::new(LockManager::new("cluster-endpoint").await?);
+
+    // Create distributed barrier for 3 participants
+    let barrier = DistributedBarrier::new(
+        lock_manager.clone(),
+        "sync-point",
+        3
+    );
+
+    // Spawn multiple tasks
+    let mut handles = vec![];
+
+    for i in 0..3 {
+        let barrier = barrier.clone();
+        let handle = tokio::spawn(async move {
+            println!("Task {} doing work...", i);
+
+            // Simulate different work durations
+            tokio::time::sleep(Duration::from_secs(i + 1)).await;
+
+            println!("Task {} waiting at barrier", i);
+            barrier.wait().await.unwrap();
+
+            println!("Task {} passed barrier", i);
+        });
+
+        handles.push(handle);
+    }
+
+    // Wait for all tasks to complete
+    for handle in handles {
+        handle.await?;
+    }
+
+    Ok(())
+}
+```
+
+### Lock with Automatic Renewal
+
+```rust
+use rustfs_lock::{DistributedLock, LockManager, LockOptions};
+use std::time::Duration;
+
+async fn auto_renewal_example() -> Result<(), Box<dyn std::error::Error>> {
+    let lock_manager = LockManager::new("cluster-endpoint").await?;
+
+    let lock_options = LockOptions {
+        timeout: Duration::from_secs(10),
+        auto_renew: true,
+        renew_interval: Duration::from_secs(3),
+        max_renewals: 5,
+        ..Default::default()
+    };
+
+    let lock = lock_manager.acquire_lock("long-running-task", lock_options).await?;
+
+    // Long-running operation
+    for i in 0..20 {
+        println!("Working on step {}", i);
+        tokio::time::sleep(Duration::from_secs(2)).await;
+
+        // Check if lock is still valid
+        if !lock.is_valid().await? {
+            println!("Lock lost, aborting operation");
+            break;
+        }
+    }
+
+    lock.release().await?;
+    Ok(())
+}
+```
+
+### Hierarchical Locking
+
+```rust
+use rustfs_lock::{LockManager, LockHierarchy, LockOptions};
+
+async fn hierarchical_locking_example() -> Result<(), Box<dyn std::error::Error>> {
+    let lock_manager = LockManager::new("cluster-endpoint").await?;
+
+    // Create lock hierarchy
+    let hierarchy = LockHierarchy::new(vec![
+        "global-lock".to_string(),
+        "bucket-lock".to_string(),
+        "object-lock".to_string(),
+    ]);
+
+    // Acquire locks in hierarchy order
+    let locks = lock_manager.acquire_hierarchical_locks(
+        hierarchy,
+        LockOptions::default()
+    ).await?;
+
+    // Critical section with hierarchical locks
+    {
+        println!("All hierarchical locks acquired");
+        // Perform operations that require the full lock hierarchy
+        tokio::time::sleep(Duration::from_secs(1)).await;
+    }
+
+    // Locks are automatically released in reverse order
+    locks.release_all().await?;
+
+    Ok(())
+}
+```
+
+## 🏗️ Architecture
+
+### Lock Architecture
+
+```
+Lock Architecture:
+┌─────────────────────────────────────────────────────────────┐
+│                    Lock API Layer                           │
+├─────────────────────────────────────────────────────────────┤
+│   Mutex    │   Semaphore   │   Barrier   │   Condition     │
+├─────────────────────────────────────────────────────────────┤
+│              Lock Manager                                   │
+├─────────────────────────────────────────────────────────────┤
+│   Consensus   │   Heartbeat   │   Timeout   │   Recovery    │
+├─────────────────────────────────────────────────────────────┤
+│              Distributed Coordination                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Lock Types
+
+| Type | Use Case | Guarantees |
+|------|----------|------------|
+| Exclusive | Critical sections | Mutual exclusion |
+| Shared | Reader-writer | Multiple readers |
+| Semaphore | Resource pooling | Counting semaphore |
+| Barrier | Synchronization | Coordination point |
+
+## 🧪 Testing
+
+Run the test suite:
+
+```bash
+# Run all tests
+cargo test
+
+# Test distributed locking
+cargo test distributed_lock
+
+# Test synchronization primitives
+cargo test sync_primitives
+
+# Test fault tolerance
+cargo test fault_tolerance
+```
+
+## 📋 Requirements
+
+- **Rust**: 1.70.0 or later
+- **Platforms**: Linux, macOS, Windows
+- **Network**: Cluster connectivity required
+- **Consensus**: Raft consensus for critical operations
+
+## 🌍 Related Projects
+
+This module is part of the RustFS ecosystem:
+
+- [RustFS Main](https://github.com/rustfs/rustfs) - Core distributed storage system
+- [RustFS Common](../common) - Common types and utilities
+- [RustFS Protos](../protos) - Protocol buffer definitions
+
+## 📚 Documentation
+
+For comprehensive documentation, visit:
+
+- [RustFS Documentation](https://docs.rustfs.com)
+- [Lock API Reference](https://docs.rustfs.com/lock/)
+- [Distributed Systems Guide](https://docs.rustfs.com/distributed/)
+
+## 🔗 Links
+
+- [Documentation](https://docs.rustfs.com) - Complete RustFS manual
+- [Changelog](https://github.com/rustfs/rustfs/releases) - Release notes and updates
+- [GitHub Discussions](https://github.com/rustfs/rustfs/discussions) - Community support
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](https://github.com/rustfs/rustfs/blob/main/CONTRIBUTING.md) for details.
+
+## 📄 License
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/rustfs/rustfs/blob/main/LICENSE) for details.
+
+---
+
+<p align="center">
+  <strong>RustFS</strong> is a trademark of RustFS, Inc.<br>
+  All other trademarks are the property of their respective owners.
+</p>
+
+<p align="center">
+  Made with 🔒 by the RustFS Team
+</p>