Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,20 @@ watchCancel() // Stop the watchdog
lock.Release(ctx, key, fencing)
```

You can also customize the extension interval using `WatchWithInterval`:

```go
// Check every 1 second instead of default ttl/2
redlock.WatchWithInterval(watchCtx, lock, key, fencing, ttl, 1*time.Second)
```

> [!WARNING]
> The watchdog goroutine (`Watch` or `WatchWithInterval`) will **not** stop automatically if the lock is lost or fails to extend. It will continue attempting to extend the lock indefinitely until the provided `context` is canceled.
>
> **Design Rationale:** This behavior is intentional to handle cases where the watchdog is started before the lock is successfully acquired (e.g., during a retry loop) or to survive transient network failures. It avoids prematurely killing the watchdog due to temporary errors.
>
> Always ensure you cancel the context when the operation is finished or if you detect that the lock has been lost.

## Error Handling

The package provides sentinel errors for reliable error checking:
Expand Down
30 changes: 28 additions & 2 deletions common.go
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,37 @@ import (
// It is designed to be used for long-running operations where the duration is unknown.
// The watchdog stops when the provided context is canceled.
//
// WARNING: Do not use context.Background() without a cancel mechanism (e.g. WithCancel),
// The watchdog attempts to extend the lock at intervals of TTL/2.
//
// WARNING(trviph): Do not use context.Background() without a cancel mechanism (e.g. WithCancel),
// otherwise the watchdog will never terminate.
//
// BUG(trviph): The Watch function relies on TryExtend. When using a DistributedLock, it suffers
// from the partial extension issue on quorum failure. If DistributedLock.TryExtend fails to
// achieve quorum, the successfully extended instances remain locked until TTL expires.
//
// This bug will probably never be fixed. Do not use Watch with DistributedLock if you are not
// comfortable with this uncertainty.
func Watch(ctx context.Context, locker Locker, key, fencing string, ttl time.Duration) {
WatchWithInterval(ctx, locker, key, fencing, ttl, ttl/2)
}

// WatchWithInterval starts a watchdog goroutine that periodically extends the lock's TTL.
// It allows customizing the interval between extension attempts.
// The watchdog stops when the provided context is canceled.
//
// WARNING(trviph): Do not use context.Background() without a cancel mechanism (e.g. WithCancel),
// otherwise the watchdog will never terminate.
//
// BUG(trviph): The WatchWithInterval function relies on TryExtend. When using a DistributedLock,
// it suffers from the partial extension issue on quorum failure. If DistributedLock.TryExtend fails to
// achieve quorum, the successfully extended instances remain locked until TTL expires.
//
// This bug will probably never be fixed. Do not use WatchWithInterval with DistributedLock if you are not
// comfortable with this uncertainty.
func WatchWithInterval(ctx context.Context, locker Locker, key, fencing string, ttl, interval time.Duration) {
go func() {
ticker := time.NewTicker(ttl / 2)
ticker := time.NewTicker(interval)
defer ticker.Stop()
for {
select {
Expand Down
8 changes: 6 additions & 2 deletions dislock.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,9 @@ import (
// BUG(trviph): The Extend and TryExtend methods do not release partially-extended locks on
// quorum failure. Unlike Acquire/TryAcquire/AcquireOrExtend, if Extend/TryExtend fails to
// achieve quorum, the successfully extended instances remain locked until TTL expires.
//
// This bug will probably never be fixed. Do not use Extend/TryExtend if you are not comfortable
// with this uncertainty.
type DistributedLock struct {
locks []*Lock
clockDriftFactor float64
Expand Down Expand Up @@ -263,9 +266,10 @@ func (dl *DistributedLock) TryExtend(ctx context.Context, key, fencing string, t
// (N/2 + 1) of instances to succeed.
// Also validates that the lock is still valid after the operation by checking clock drift.
//
// WARNING: On failure (quorum not achieved or clock drift expired), this method releases ALL
// WARNING(trviph): On failure (quorum not achieved or clock drift expired), this method releases ALL
// locks across ALL instances, including any locks that were already held before this call.
// If you need to preserve an existing lock on failure, use [DistributedLock.TryExtend] instead.
// If you need to preserve an existing lock on failure, use [DistributedLock.Extend]
// or [DistributedLock.TryExtend] instead.
//
// Returns an error if quorum cannot be achieved, clock drift check fails, or context is cancelled.
func (dl *DistributedLock) AcquireOrExtend(ctx context.Context, key, fencing string, ttl time.Duration) (err error) {
Expand Down
15 changes: 15 additions & 0 deletions doc.go
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
// - Atomic acquisition and release using Lua scripts
// - Fencing tokens (UUIDs) to prevent unsafe lock hand-off
// - Lock extension for long-running operations
// - Watchdog pattern support via [Watch] and [WatchWithInterval]
//
// Example usage:
//
Expand Down Expand Up @@ -59,6 +60,20 @@
// - [DistributedLock]: [WithClockDriftFactor], [WithClockDriftBuffer], [WithReleaseTimeout],
// [WithDistMaxRetry], [WithDistMinRetryDelay], [WithDistMaxJitterDuration]
//
// # Watchdog Pattern
//
// [Watch] and [WatchWithInterval] provide a background goroutine to automatically extend
// the lock duration.
//
// Warning: The watchdog will **not** stop automatically if the lock is lost or fails
// to extend. It will continue attempting to extend the lock indefinitely until the
// provided context is canceled.
//
// This design handles cases where the watchdog is started before the lock is successfully
// acquired (e.g., in a background retry loop) and ensures resilience against transient
// network failures. The user is responsible for managing the watchdog's lifecycle via
// the context.
//
// # Sentinel Errors
//
// The package exports sentinel errors for reliable error checking with [errors.Is]:
Expand Down