How orx Uses a Lifecycle Lock for Atomic Destructive Operations

orx employs a process-wide file-based lifecycle lock via fd_lock::RwLock to ensure that destructive operations like delete execute exclusively while preventing concurrent mutations from corrupting persistent state.

The alphaXiv/OpenResearch repository implements this orx lifecycle lock mechanism to protect the integrity of the local datastore. By leveraging file-descriptor locking on a persistent lock file (orx.lifecycle.lock), the tool coordinates access across independent processes, ensuring that dangerous operations run atomically.

Architecture of the Lifecycle Lock

The lock implementation centers on the fd_lock::RwLock<std::fs::File> type, which provides a cross-process read-write lock primitive. In src/store.rs:39-48, the open_lifecycle_lock() function initializes this mechanism by creating or opening the lock file within the user's configuration directory.

pub(crate) fn open_lifecycle_lock() -> Result<fd_lock::RwLock<std::fs::File>> {
    open_lifecycle_lock_at(&lifecycle_lock_path())
}

The lock file resides at crate::config::config_dir().join("orx.lifecycle.lock"), ensuring consistent path resolution across platforms. This file-backed approach allows the lock to persist beyond process lifetimes, enabling coordination between completely separate orx invocations.

Runtime Lock Acquisition in main.rs

In src/main.rs:874, the application inspects incoming commands using command_uses_lifecycle_lock() to determine if the operation requires synchronization. When a state-changing command executes, the code stores the returned lock guard in _lifecycle_guard, which remains alive for the entire command duration.

let uses_lock = command_uses_lifecycle_lock(&command);
let lifecycle_lock = uses_lock.then(store::open_lifecycle_lock).transpose()?;
let _lifecycle_guard = lifecycle_lock
    .as_ref()
    .map(|lock| lock.read())
    .transpose()?;

As shown in src/main.rs:1036-1037, this guard pattern ensures the lock automatically releases when the command completes, regardless of success or failure. The lock acquisition happens before any state mutation begins, establishing a clear ordering guarantee.

Write Locks for Destructive Operations

Destructive operations such as delete require exclusive access to prevent race conditions during data removal. In src/commands/delete.rs:34-35, the command attempts to acquire a write lock using try_write(), which fails immediately if another process holds the lock rather than blocking indefinitely.

let mut lifecycle_lock = crate::store::open_lifecycle_lock()?;
let _lifecycle_guard = lifecycle_lock
    .try_write()
    .map_err(|error| anyhow!("cannot acquire lifecycle lock: {error}"))?;

If try_write() returns an error, the command aborts with a clear diagnostic message indicating concurrent operation. This non-blocking strategy prevents destructive commands from hanging when the datastore is busy, while ensuring that only one destructive operation proceeds at a time.

Read Locks for Non-Destructive Queries

Commands that merely inspect state without modification—such as listing running experiments—acquire a shared read lock instead. As implemented in src/main.rs:1036, these operations call lock.read(), allowing multiple concurrent readers to coexist safely.

While readers hold the lock, destructive writers block until all shared locks drop. This design maximizes throughput for read-heavy workflows while maintaining safety guarantees for mutations.

Internal Storage Utilities and Lock Propagation

Lower-level modules also participate in the locking protocol. In src/local/storage.rs:31-33, the open_lifecycle_lock_at() helper provides the same locking primitive for internal data-directory moves and storage maintenance operations.

This ensures that even utility functions respect the lifecycle boundaries, preventing filesystem-level race conditions when the application reorganizes its internal storage layout.

Summary

• orx uses a file-backed fd_lock::RwLock stored at orx.lifecycle.lock to coordinate process-wide access.
• The store::open_lifecycle_lock() function in src/store.rs:39-48 initializes the lock file with cross-platform path resolution.
• Destructive commands in src/commands/delete.rs:34-35 acquire exclusive write locks via try_write() for atomic execution.
• Non-destructive commands obtain shared read locks through lock.read() in src/main.rs:1036, enabling concurrent read access.
• The _lifecycle_guard pattern in src/main.rs:1036-1037 ensures automatic lock release via RAII when commands complete.

Frequently Asked Questions

How does the orx lifecycle lock prevent race conditions between separate processes?

The lock uses a file-descriptor-based RwLock from the fd_lock crate, which relies on operating-system primitives to coordinate access across processes. When one orx process holds the lock file, the OS prevents other processes from acquiring conflicting locks, ensuring that destructive operations like delete cannot overlap with other mutations.

What happens if an orx command crashes while holding the lifecycle lock?

Since the lock relies on file descriptors, the operating system automatically releases the lock when the process terminates or the file descriptor closes. The _lifecycle_guard variable in src/main.rs holds the lock handle for the command duration, so even if the command panics or exits unexpectedly, the RAII drop semantics ensure the lock releases immediately.

Why does orx use try_write() instead of write() for destructive operations?

The try_write() method returns immediately with an error if the lock is unavailable, rather than blocking the process indefinitely. As seen in src/commands/delete.rs:34-35, this allows destructive commands to fail fast with a clear message instead of hanging when another orx instance is actively mutating the datastore.

Can multiple read-only commands run simultaneously with the lifecycle lock?

Yes, non-destructive commands acquire a shared read lock via lock.read() as shown in src/main.rs:1036. The fd_lock::RwLock implementation allows multiple concurrent readers to hold the lock simultaneously, provided no writer currently holds it. This design optimizes for read-heavy usage patterns while still excluding writers during active reads.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}