agentslock

func AcquireFileLock ¶ added in v0.4.2

func AcquireFileLock(path string) (release func() error, err error)

AcquireFileLock takes the package's advisory, inter-process lock guarding the file at path and returns a release function the caller MUST invoke to free it. It is the reusable form of the primitive that serializes .agentsrc.lock writes (see Flush); other cooperating da processes (e.g. an append-only NDJSON writer) call it to serialize their own writes to a shared file.

The lock is a sidecar directory at "<path>.lock". Acquisition is a single atomic os.Mkdir: success is the mutual-exclusion signal, and EEXIST means another holder currently owns it. The lock is therefore ADVISORY — it excludes only other callers of this function that name the same path, not arbitrary writers of the underlying file. The parent directory of path is created if it does not yet exist.

Acquisition blocks up to lockAcquireTimeout, retrying every lockRetryInterval, and returns a timeout error if a live holder never releases. Because the mkdir lock has no kernel-backed auto-release, a holder that crashed without releasing (SIGKILL/OOM/power loss) is detected as stale once its recorded age exceeds lockStaleTTL and is reclaimed at most once per call — so a slow but live holder is never torn down out from under itself. The returned release removes the sidecar directory exactly once and reports any removal error; it is once-guarded (a second call returns the first call's cached error without touching the filesystem).

The once-guard is a correctness requirement, not a convenience: an unguarded RemoveAll on every call would, after this caller released and another caller re-acquired the same path, delete the new holder's live lock dir on a stray second release — silently breaking its mutual exclusion. Removing at most once guarantees a duplicate release can never delete a dir this caller no longer owns.