Locks API for Go

Every public type, function and constant of the Locks engine in tinyshed.org/tinystore/locks, generated from its source. The Locks guide explains how to use them, and the Bun and Node, Python and Rust pages list the same API.

#Fence

type Fence struct {
	// contains filtered or unexported fields
}

Fence grows with every lease the store gives a lock, 128 bits: hand it to whatever must refuse a late holder, which keeps the greatest it saw.

#Fence.Less

func (f Fence) Less(other Fence) bool

Less says f came before other.

#Fence.String

func (f Fence) String() string

String is the fence in decimal, as the store writes it.

#HoldOption

type HoldOption func(*time.Duration)

HoldOption is how a hold waits.

#Wait

func Wait(d time.Duration) HoldOption

Wait is how long a hold waits in line for its key, 10 s unless given: a key still held past it is ErrInUse.

#Lease

type Lease struct {
	Fence Fence
}

Lease is a holding of a key: a lock's Fence, none for a semaphore's.

#Lock

type Lock struct {
	// contains filtered or unexported fields
}

Lock is keys held one holder at a time.

#OpenLock

func OpenLock(store *tinystore.Store, name string, opts ...Option) (*Lock, error)

OpenLock opens a lock: keys held one holder at a time, across every program of the store.

#Lock.Hold

func (l *Lock) Hold(ctx context.Context, key any, fn func(ctx context.Context, lease *Lease) error, opts ...HoldOption) error

Hold waits for key in line, holds it while fn runs and lets it go. A key still held past the wait is ErrInUse; a lease lost while fn ran ends its ctx, and Hold is ErrLost though fn succeeded, since another holder may have run beside it.

#Lock.TryHold

func (l *Lock) TryHold(ctx context.Context, key any, fn func(ctx context.Context, lease *Lease) error) (bool, error)

TryHold holds key while fn runs if nobody holds it, and says whether it did.

#Option

type Option func(*keys)

Option is how a lock or a semaphore opens.

#Limit

func Limit(n int) Option

Limit is how many may hold a semaphore's key at once, 1 to 1000.

#MaxHold

func MaxHold(d time.Duration) Option

MaxHold is how long a lease lasts from its grant, however it is renewed: past it the next in line holds the key, and the holder's ctx ends.

#TTL

func TTL(d time.Duration) Option

TTL is how long a lease lasts from its last renewal, 1 s to 1 hour, 10 s unless given; this program renews it at a third of it while the function runs.

#Semaphore

type Semaphore struct {
	// contains filtered or unexported fields
}

Semaphore is keys held by up to their limit at a time.

#OpenSemaphore

func OpenSemaphore(store *tinystore.Store, name string, opts ...Option) (*Semaphore, error)

OpenSemaphore opens a semaphore: each key held by up to Limit holders at once.

#Semaphore.Hold

func (s *Semaphore) Hold(ctx context.Context, key any, fn func(ctx context.Context, lease *Lease) error, opts ...HoldOption) error

Hold waits for one of key's permits in line and holds it while fn runs, as a lock's Hold does.

#Semaphore.TryHold

func (s *Semaphore) TryHold(ctx context.Context, key any, fn func(ctx context.Context, lease *Lease) error) (bool, error)

TryHold holds one of key's permits while fn runs if one is free, and says whether it did.