diff --git a/README.md b/README.md index 94e5a74..95c2ce6 100644 --- a/README.md +++ b/README.md @@ -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: diff --git a/common.go b/common.go index 29108e2..b567f54 100644 --- a/common.go +++ b/common.go @@ -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 { diff --git a/dislock.go b/dislock.go index 45731e5..387d4e1 100644 --- a/dislock.go +++ b/dislock.go @@ -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 @@ -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) { diff --git a/doc.go b/doc.go index c1070ea..b72b646 100644 --- a/doc.go +++ b/doc.go @@ -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: // @@ -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]: