aeat.adapters.persistence.storage.bucket._lockfile module

Per-bucket .lock concurrency primitive for the bucket directory model.

Each bucket carries a single PID-stamped lockfile at <bucket-dir>/.lock created via os.open with O_CREAT | O_EXCL | O_WRONLY; the O_EXCL flag is atomic on every POSIX kernel and on Windows NTFS, so a second-process unlock against a held bucket fails fast with adapters.persistence.storage.bucket.BucketBusyError per the substrate locking contract.

The lockfile carries the holder’s PID. A stale lock (PID is no longer a live process) is reclaimed lazily by the acquiring process so an abnormal process exit (SIGKILL, OS crash, container OOM) does not permanently strand the bucket; the lazy reclaim is documented under the plan’s “Lockfile staleness detection” open question.

lock_path(paths)

Return the canonical lockfile path for the bucket.

Return type:

Path

Parameters:

paths (BucketPaths)

acquire_lock(paths, *, wait_seconds=0.0)

Acquire the per-bucket lockfile or raise BucketBusyError.

Parameters:

• paths (BucketPaths) – The bucket paths whose .lock to acquire.

• wait_seconds (float) – Maximum time to wait for the lock to become free. Defaults to 0.0 (no wait); callers that want bounded waiting pass a positive value.

Raises:

BucketBusyError – When the lockfile is held by a live process and the wait window expires.

Return type:

None

release_lock(paths)

Release the per-bucket lockfile owned by this process.

Removes the lockfile only when the recorded PID matches this process; a foreign lockfile is left alone so a stale-reclaim race cannot delete another process’s lock.

Return type:

None

Parameters:

paths (BucketPaths)