Struct CacheLock 

pub struct CacheLock { /* private fields */ }

A file lock for cache operations.

The lock is held for the lifetime of this struct and automatically released when dropped. Lock acquisition and release are tracked for deadlock detection.

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.

Creates and acquires an exclusive file lock for the specified source name. Uses non-blocking lock attempts with exponential backoff and timeout.

Lock File Management

1. Creates .locks/ directory if needed
2. Creates {source_name}.lock file
3. Acquires exclusive access via OS file locking
4. Keeps file handle open to maintain lock

Behavior

• Timeout: 30-second default (configurable via acquire_with_timeout)
• Non-blocking: try_lock_exclusive() in async retry loop
• Backoff: 10ms → 20ms → 40ms… up to 500ms max
• Fair access: FIFO order typically
• Interruptible: Process signals work

Lock File Location

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

Example: ~/.agpm/cache/.locks/community.lock

Errors

• Permission denied
• Disk space exhausted
• Timeout acquiring lock

Platform Support

• Windows: Win32 LockFile API
• Unix: POSIX fcntl() locking

Examples

use agpm_cli::cache::lock::CacheLock;
use std::path::Path;
let lock = CacheLock::acquire(cache_dir, "my-source").await?;
// Lock released on drop

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

Acquires an exclusive lock with a specified timeout.

Uses exponential backoff (10ms → 500ms) without blocking the async runtime.

Errors

Returns timeout error if lock cannot be acquired within the specified duration.

Examples

use agpm_cli::cache::lock::CacheLock;
use std::time::Duration;
use std::path::Path;
let lock = CacheLock::acquire_with_timeout(
    cache_dir, "my-source", Duration::from_secs(10)
).await?;

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

Acquires a shared (read) lock for a specific source in the cache directory.

Multiple processes can hold shared locks simultaneously, but a shared lock blocks exclusive lock acquisition. Use this for operations that can safely run in parallel, like worktree creation (each SHA writes to a different subdir).

Lock Semantics

• Shared locks: Multiple holders allowed simultaneously
• Exclusive locks: Blocked while any shared lock is held
• Shared + Exclusive: Shared lock blocks until exclusive is released

Use Cases

• Worktree creation: Multiple SHAs can create worktrees in parallel
• Read-only operations on shared state

Examples

use agpm_cli::cache::lock::CacheLock;
use std::path::Path;
// Multiple processes can hold this simultaneously
let lock = CacheLock::acquire_shared(cache_dir, "bare-worktree-owner_repo").await?;
// Lock released on drop

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

Acquires a shared (read) lock with a specified timeout.

Uses exponential backoff (10ms → 500ms) without blocking the async runtime.

Errors

Returns timeout error if lock cannot be acquired within the specified duration.

Trait Implementations

impl Debug for CacheLock

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for CacheLock

fn drop(&mut self)

Executes the destructor for this type.