Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrLockUnsuccessful = errors.New("store is locked") ErrUnlockUnsuccessful = errors.New("could not unlock store") )
Functions ¶
This section is empty.
Types ¶
type UnlockFunc ¶
type UnlockFunc func() error
UnlockFunc is the callback returned by TryLock and TryRLock. It releases the advisory lock, closes the underlying file descriptor, and stops the background heartbeat goroutine that refreshes the lock file's modtime.
Callers MUST invoke this function exactly once, typically via defer immediately after a successful lock acquisition. Failing to call it leaks both the file descriptor and the heartbeat goroutine for the remaining lifetime of the process — the goroutine has no other termination signal. Calling it more than once is safe and idempotent; only the first call performs the release.
The returned error reflects the unlock/close step only. The heartbeat goroutine is always stopped and joined before the unlock is attempted, so the file descriptor is never touched after it has been closed.
func TryLock ¶
TryLock acquires an exclusive advisory lock on a lock file.
If the file does not exist, it is created. If the lock cannot be acquired immediately, the function retries until ctx is canceled or the lock is acquired.
As a safeguard, the function attempts to recover from stale locks, defined as lock files older than 30s. While the lock is held, a background goroutine refreshes the lock file's modtime every 10s so long-running operations are not misclassified as stale. Stale lock recovery is skipped when ctx has been canceled. If recovery fails, manual intervention may be required.
The heartbeat goroutine surfaces truncate failures and hijack detections through the logging.Logger stored on ctx via logging.WithLogger. When no logger is set, those events are dropped silently — the package never writes to a default sink.
On success, the returned UnlockFunc MUST be called exactly once to release the lock, close the file descriptor, and stop the heartbeat goroutine. The idiomatic pattern is to defer it immediately:
ctx = logging.WithLogger(ctx, myLogger) // optional
unlock, err := flock.TryLock(ctx, root)
if err != nil {
return err
}
defer unlock()
Failing to call the returned function leaks both the file descriptor and the heartbeat goroutine for the remaining lifetime of the process. See UnlockFunc for details.
func TryRLock ¶
TryRLock acquires a non-exclusive advisory lock on a lock file.
If the file does not exist, it is created. If the lock cannot be acquired immediately, the function retries until ctx is canceled or the lock is acquired.
As a safeguard, the function attempts to recover from stale locks, defined as lock files older than 30s. While the lock is held, a background goroutine refreshes the lock file's modtime every 10s so long-running operations are not misclassified as stale. Stale lock recovery is skipped when ctx has been canceled. If recovery fails, manual intervention may be required.
The heartbeat goroutine surfaces truncate failures and hijack detections through the logging.Logger stored on ctx via logging.WithLogger. When no logger is set, those events are dropped silently — the package never writes to a default sink.
On success, the returned UnlockFunc MUST be called exactly once to release the lock, close the file descriptor, and stop the heartbeat goroutine. The idiomatic pattern is to defer it immediately:
ctx = logging.WithLogger(ctx, myLogger) // optional
unlock, err := flock.TryRLock(ctx, root)
if err != nil {
return err
}
defer unlock()
Failing to call the returned function leaks both the file descriptor and the heartbeat goroutine for the remaining lifetime of the process. See UnlockFunc for details.
Source Files