FileLock
in package
Advisory file lock with a liveness heartbeat.
A lock is considered abandoned once its file has not been touched for $maxAge seconds. That only means "the owner died" if a working owner keeps touching it, so long-running work refreshes every lock this process holds — see refreshHeld(), called from TsService::throttleWrite() after each write chunk. Without the heartbeat, age would just measure how long the job takes, and a slow flush would look abandoned while it was still writing.
Table of Contents
Properties
- $held : array<string, self>
- Locks held by this process, so a long job can prove it is still alive.
- $lockFile : string
- $maxAge : int
Methods
- __construct() : mixed
- acquire() : bool
- Attempts to acquire a file lock. Returns true if successful, false if lock already exists.
- exists() : bool
- Whether a lock file is present at all, live or abandoned.
- getAge() : int|null
- Seconds since the lock was last touched, or null when there is no lock.
- isLocked() : bool
- Whether a live lock is held.
- refresh() : void
- Marks this lock as still alive.
- refreshHeld() : void
- Heartbeat for every lock this process holds.
- release() : void
- Releases the file lock by deleting the lock file.
- isStale() : bool
Properties
$held
Locks held by this process, so a long job can prove it is still alive.
private
static array<string, self>
$held
= []
$lockFile
private
string
$lockFile
$maxAge
private
int
$maxAge
Methods
__construct()
public
__construct(string $lockName[, int $maxAge = 1800 ]) : mixed
Parameters
- $lockName : string
- $maxAge : int = 1800
acquire()
Attempts to acquire a file lock. Returns true if successful, false if lock already exists.
public
acquire() : bool
Abandoned locks older than $maxAge seconds are automatically released.
Return values
bool —True if lock acquired, false if already locked.
exists()
Whether a lock file is present at all, live or abandoned.
public
exists() : bool
For callers that clean up rather than coordinate, e.g. wp wsc flush-unlock.
Return values
boolgetAge()
Seconds since the lock was last touched, or null when there is no lock.
public
getAge() : int|null
Return values
int|nullisLocked()
Whether a live lock is held.
public
isLocked() : bool
Mirrors acquire(): a lock nothing has touched for $maxAge is abandoned, not held. These two used to disagree — acquire() self-healed while isLocked() was a bare file_exists() — so a single interrupted flush blocked every later flush and stalled the PIM buffer cron indefinitely.
Return values
boolrefresh()
Marks this lock as still alive.
public
refresh() : void
refreshHeld()
Heartbeat for every lock this process holds.
public
static refreshHeld() : void
Called from long write loops so work in progress never looks abandoned.
release()
Releases the file lock by deleting the lock file.
public
release() : void
isStale()
private
isStale() : bool