distributedlock

func NewScopedLocker ¶

func NewScopedLocker(
	locker Locker,
	logger logging.Logger,
	tracerProvider tracing.TracerProvider,
	metricsProvider metrics.Provider,
	opts ...ScopedOption,
) (ScopedLocker, error)

NewScopedLocker wraps any Locker in scoped execution. WithLock waits for a contended lock by polling Acquire (the Locker atom deliberately has no queueing of its own); providers with native waiting (postgres) ship their own ScopedLocker and don't need this adapter.

It takes the standard observability triple so that the scoped surface emits the same telemetry whichever Locker backs it: the wrapped Locker's own Acquire/Release instrumentation describes individual attempts, while scoped_lock_* describes the whole acquire-run-release operation, including fn's duration and the time spent waiting.

package main

import (
	"context"
	"fmt"

	"github.com/primandproper/platform-go/v7/distributedlock"
	"github.com/primandproper/platform-go/v7/distributedlock/memory"
)

func main() {
	ctx := context.Background()

	locker, err := memory.NewLocker(nil, nil, nil)
	if err != nil {
		panic(err)
	}
	defer func() { _ = locker.Close() }()

	// nil logger, tracer provider, and metrics provider fall back to noop
	// implementations; a real service passes the ones it built at startup.
	scoped, err := distributedlock.NewScopedLocker(locker, nil, nil, nil)
	if err != nil {
		panic(err)
	}

	if err = scoped.WithLock(ctx, "nightly-compaction", func(context.Context) error {
		fmt.Println("compacting")

		return nil
	}); err != nil {
		panic(err)
	}

	// The lock was released the moment fn returned, so the next caller gets it
	// without waiting.
	ran, err := scoped.TryWithLock(ctx, "nightly-compaction", func(context.Context) error {
		fmt.Println("compacting again")

		return nil
	})
	if err != nil {
		panic(err)
	}

	fmt.Println("ran:", ran)
}

Output:
compacting
compacting again
ran: true

func WithScopedClock ¶

func WithScopedClock(c clock.Clock) ScopedOption

WithScopedClock swaps the clock used for contention polling. Tests generally do not need it: under testing/synctest the default clock already runs on bubble time, so WithLock's waiting is deterministic and instant.

func WithScopedJitter ¶

func WithScopedJitter(fn func() float64) ScopedOption

WithScopedJitter replaces the source of randomness that spreads contended waiters apart. fn must return a value in [0,1]; the adapter sleeps for half the current interval plus that fraction of the other half, so waiters that started together do not re-collide on every round.

The default draws from math/rand/v2 and needs no seeding. Tests wanting a fixed schedule can pass func() float64 { return 1 }, which yields exactly the un-jittered interval. A nil fn is ignored.

func WithScopedLockTTL ¶

func WithScopedLockTTL(ttl time.Duration) ScopedOption

WithScopedLockTTL sets the TTL the adapter passes to Acquire. The TTL must comfortably exceed fn's worst-case duration: if the underlying lock expires while fn is still running, mutual exclusion is no longer guaranteed, and the implicit release will surface ErrLockNotHeld in the returned error — and increment the scoped_lock_release_failures counter, which is the signal to alert on.

func WithScopedPollBackoff ¶

func WithScopedPollBackoff(factor float64, maxInterval time.Duration) ScopedOption

WithScopedPollBackoff sets how the contended wait grows: each successive wait is multiplied by factor and clamped to maxInterval.

Backoff exists because a fixed poll interval makes N waiters on one key a thundering herd against the underlying store — N/interval requests per second for as long as the holder runs, none of which can succeed. Growing the interval trades a bounded amount of post-release latency (at most maxInterval, and on average less because of the jitter) for a large drop in that load.

factor must be at least 1 and maxInterval at least the poll interval; NewScopedLocker rejects anything else. A factor of exactly 1 disables growth and restores a fixed interval, still jittered.

func WithScopedPollInterval ¶

func WithScopedPollInterval(interval time.Duration) ScopedOption

WithScopedPollInterval sets the first wait WithLock takes after a contended acquisition; later waits grow from it per WithScopedPollBackoff. It must be positive — a non-positive interval would turn the wait into a spin, since clock.Sleep returns immediately for a non-positive duration — and NewScopedLocker rejects it. TryWithLock never polls.