Struct CacheLock 

pub struct CacheLock { /* private fields */ }

A file lock for cache operations

Implementations

impl CacheLock

pub async fn acquire(cache_dir: &Path, source_name: &str) -> Result<Self>

Acquires an exclusive lock for a specific source in the cache directory.

This async method creates and acquires an exclusive file lock for the specified source name. The file locking operation uses spawn_blocking internally to avoid blocking the tokio runtime, while still providing blocking file lock semantics.

Lock File Management

The method performs several setup operations:

1. Locks directory creation: Creates .locks/ directory if needed
2. Lock file creation: Creates {source_name}.lock file
3. Exclusive locking: Acquires exclusive access via OS file locking
4. Handle retention: Keeps file handle open to maintain lock

Async and Blocking Behavior

If another process already holds a lock for the same source:

• Async-friendly: Uses spawn_blocking to avoid blocking the tokio runtime
• Blocking wait: The spawned task blocks until other lock is released
• Fair queuing: Locks are typically acquired in FIFO order
• No timeout: Task will wait indefinitely (use with caution)
• Interruptible: Can be interrupted by process signals

Lock File Location

Lock files are created in a dedicated subdirectory:

{cache_dir}/.locks/{source_name}.lock

Examples:

• ~/.agpm/cache/.locks/community.lock
• ~/.agpm/cache/.locks/work-tools.lock
• ~/.agpm/cache/.locks/my-project.lock

Parameters

• cache_dir - Root cache directory path
• source_name - Unique identifier for the source being locked

Returns

Returns a CacheLock instance that holds the exclusive lock. The lock remains active until the returned instance is dropped.

Errors

The method can fail for several reasons:

Directory Creation Errors

• Permission denied creating .locks/ directory
• Disk space exhausted
• Path length exceeds system limits

File Operation Errors

• Permission denied creating/opening lock file
• File system full
• Invalid characters in source name

Locking Errors

• File locking not supported by file system
• Lock file corrupted or in invalid state
• System resource limits exceeded

Platform Considerations

• Windows: Uses Win32 LockFile API via fs4
• Unix: Uses POSIX fcntl() locking via fs4
• NFS/Network: Behavior depends on file system support
• Docker: Works within containers with proper volume mounts

Examples

Simple lock acquisition:

use agpm_cli::cache::lock::CacheLock;
use std::path::PathBuf;

let cache_dir = PathBuf::from("/home/user/.agpm/cache");

// This will block if another process has the lock
let lock = CacheLock::acquire(&cache_dir, "my-source").await?;

// Perform cache operations safely...
println!("Lock acquired successfully!");

// Lock is released when 'lock' variable is dropped
drop(lock);

Error handling for lock acquisition:

use agpm_cli::cache::lock::CacheLock;
use std::path::PathBuf;

let cache_dir = PathBuf::from("/tmp/cache");

match CacheLock::acquire(&cache_dir, "problematic-source").await {
    Ok(lock) => {
        println!("Lock acquired, proceeding with operations");
        // Use lock...
    }
    Err(e) => {
        eprintln!("Failed to acquire lock: {}", e);
        eprintln!("Another process may be using this source");
        return Err(e);
    }
}