README
¶
kit/lockfile
github.com/vormadev/vorma/kit/lockfile
File-based lease lock helper for cross-process mutual exclusion with stale-lock takeover.
Import
import "github.com/vormadev/vorma/kit/lockfile"
Quick Start
lock := lockfile.NewPIDLock("./.wave-dev.lock")
if err := lock.Acquire(); err != nil {
return err
}
defer lock.Release()
// exclusive work
Custom Options
lock := lockfile.NewPIDLockWithOptions(
"./.wave-dev.lock",
lockfile.Options{
AcquireRetryLimit: 20,
AcquireRetryDelay: 25 * time.Millisecond,
InvalidPIDLockStaleThreshold: 2 * time.Second,
LeaseHeartbeatInterval: 300 * time.Millisecond,
LeaseStaleThreshold: 4 * time.Second,
},
)
Behavior Notes
- Lock files store lease JSON with schema version, owner id, pid, and heartbeat timestamp.
Acquireuses atomic create (O_EXCL) and retries briefly on stale-lock remove races.- Owners heartbeat while held; callers can take over when heartbeat is stale.
- Invalid/non-parseable lock contents are treated as held until
InvalidPIDLockStaleThreshold, then reclaimed. Releaseis ownership-fenced and will not delete another owner’s lock file.OnLeaseLostcan be used by long-running processes to fail fast when ownership is lost.
API Coverage
var ErrLockHeld errortype Options struct {HeldError errorAcquireRetryLimit intAcquireRetryDelay time.DurationInvalidPIDLockStaleThreshold time.DurationFileWriteMode fs.FileModeDirectoryWriteMode fs.FileModeProcessAppearsAlive func(processID int)(optional PID liveness override; defaults to a signal-0 probe)LeaseHeartbeatInterval time.DurationLeaseStaleThreshold time.DurationOnLeaseLost func()}type PIDLock structfunc NewPIDLock(lockFilePath string) *PIDLockfunc NewPIDLockWithOptions(lockFilePath string, options Options) *PIDLockfunc (pidLock *PIDLock) Path() stringfunc (pidLock *PIDLock) Acquire() errorfunc (pidLock *PIDLock) Release() errorfunc (pidLock *PIDLock) Held() bool
Documentation
¶
Overview ¶
Package lockfile provides cross-process file locks using lease heartbeats and stale-lock reclamation semantics for command and daemon orchestration.
Index ¶
Constants ¶
This section is empty.
Variables ¶
View Source
var ErrLockHeld = errors.New("lock file is already held by another process")
ErrLockHeld reports that another process currently owns the lock file.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
// HeldError is wrapped when an active owner is detected.
// Defaults to ErrLockHeld when unset.
HeldError error
// AcquireRetryLimit is the number of retry attempts after a stale-lock remove
// race before giving up.
AcquireRetryLimit int
// AcquireRetryDelay is the delay between lock acquisition retries.
AcquireRetryDelay time.Duration
// InvalidPIDLockStaleThreshold is the age threshold before reclaiming lock
// files that do not contain a parseable lease record.
InvalidPIDLockStaleThreshold time.Duration
// FileWriteMode is used when creating lock files.
FileWriteMode fs.FileMode
// DirectoryWriteMode is used when creating parent directories.
DirectoryWriteMode fs.FileMode
// ProcessAppearsAlive is ignored and retained only for API stability.
ProcessAppearsAlive func(processID int) bool
// LeaseHeartbeatInterval controls heartbeat write cadence while lock is held.
// Defaults to 250ms when unset.
LeaseHeartbeatInterval time.Duration
// LeaseStaleThreshold is the stale lease threshold before takeover.
// Defaults to 3s when unset.
LeaseStaleThreshold time.Duration
// OnLeaseLost is called when ownership is lost while the lock is held.
OnLeaseLost func()
}
Options controls lock-file behavior.
type PIDLock ¶
type PIDLock struct {
// contains filtered or unexported fields
}
PIDLock manages exclusive ownership for one lock-file path using lease files.
func NewPIDLock ¶
NewPIDLock creates a lock using default lock options.
func NewPIDLockWithOptions ¶
NewPIDLockWithOptions creates a lock with explicit options.
Source Files
Click to show internal directories.
Click to hide internal directories.