Documentation
¶
Overview ¶
Package sink provides alternates to sync, inspired by the talk Rethinking Classical Concurrency Patterns.
Index ¶
- Constants
- func FromMonitor[T any, U any](ctx context.Context, mon Monitor[T], cond func(T) bool, ...) (U, error)
- func FromMonitors[T any, U any, V any](ctx context.Context, m0 Monitor[T], m1 Monitor[U], c0 func(T) bool, ...) (V, error)
- func FromMutex[T any, U any](ctx context.Context, mu Mutex[T], fn ExclusiveAccessValuer[T, U]) (U, error)
- func FromPriorityMutex[T any, U any](ctx context.Context, mu PriorityMutex[T], priority Priority, ...) (U, error)
- type ExclusiveAccess
- type ExclusiveAccessValuer
- type ExclusiveMultiAccessValuer
- type Gate
- type Monitor
- type Mutex
- type PreemptibleExclusiveAccess
- type PreemptibleExclusiveAccessValuer
- type Priority
- type PriorityMutex
Constants ¶
const ( MinPriority = Priority(0) MaxPriority = Priority(math.MaxUint) )
Idiomatic Priority bounds.
Variables ¶
This section is empty.
Functions ¶
func FromMonitor ¶
func FromMonitor[T any, U any](ctx context.Context, mon Monitor[T], cond func(T) bool, fn ExclusiveAccessValuer[T, U]) (U, error)
FromMonitor is a convenience wrapper around Monitor.Wait, returning a value derived from the guarded value.
func FromMonitors ¶
func FromMonitors[T any, U any, V any]( ctx context.Context, m0 Monitor[T], m1 Monitor[U], c0 func(T) bool, c1 func(U) bool, fn ExclusiveMultiAccessValuer[T, U, V], ) (V, error)
FromMonitors is a convenience wrapper around nested calls to FromMonitor, returning a value derived from both guarded values. Waiting is performed in the same order as the condition arguments, so `m0` is locked the longest.
func FromMutex ¶
func FromMutex[T any, U any](ctx context.Context, mu Mutex[T], fn ExclusiveAccessValuer[T, U]) (U, error)
FromMutex is a convenience wrapper around Mutex.Use, returning a value derived from the guarded value, which is unchanged.
func FromPriorityMutex ¶
func FromPriorityMutex[T any, U any](ctx context.Context, mu PriorityMutex[T], priority Priority, fn PreemptibleExclusiveAccessValuer[T, U]) (U, error)
FromPriorityMutex is a convenience wrapper around PriorityMutex.Use, returning a value derived from the guarded value, which is unchanged.
Types ¶
type ExclusiveAccess ¶
An ExclusiveAccess function receives a guarded value with a guarantee of mutual exclusion. Any error returned by an ExclusiveAccess function is propagated.
type ExclusiveAccessValuer ¶
An ExclusiveAccessValuer function is equivalent to an ExclusiveAccess function except that it returns a value in addition to an error. T and U MAY be the same type.
type Gate ¶
type Gate struct {
// contains filtered or unexported fields
}
A Gate blocks waiters until it is opened. Unlike a closed channel, it can be reused.
func (Gate) Block ¶
func (g Gate) Block()
Block blocks all future calls to Gate.Wait until Gate.Open is called. Repeated calls are idempotent.
type Monitor ¶
type Monitor[T any] struct { // contains filtered or unexported fields }
A Monitor is a mutual exclusion lock, guarding a specific value, with the added ability to wait until a condition predicated on the value is met. It is intended as an alternative to `sync.Cond`.
The zero value of a Monitor is invalid. It is safe to copy a Monitor.
func NewMonitor ¶
NewMonitor creates a new Monitor and sets the initial value to `init`. Call Monitor.Close to release resources.
func (Monitor[T]) Close ¶
func (m Monitor[T]) Close() T
Close releases the Monitors's resources. Any future calls to Monitor.UseThenSignal or Monitor.Wait will return an error. Close returns the guarded value.
func (Monitor[T]) UseThenSignal ¶
func (m Monitor[T]) UseThenSignal(ctx context.Context, fn ExclusiveAccess[T]) error
UseThenSignal calls `fn` with the guarded value, returning immediately if `fn` returns an error (which is propagated). Otherwise, the conditions of all goroutines blocked by Monitor.Wait are checked and those that return true receive the guarded value for their own, respective ExclusiveAccess functions.
func (Monitor[T]) Wait ¶
Wait calls `cond` with the guarded value, one or more times, until it returns true, after which it calls `fn` with the guarded value. Repeated calls to `cond` will be blocked until signalled via a concurrent call to Monitor.UseThenSignal.
type Mutex ¶
type Mutex[T any] struct { // contains filtered or unexported fields }
A Mutex is a mutual exclusion lock that guards a specific value. The zero value of a Mutex is invalid. It is safe to copy a Mutex.
func NewMutex ¶
NewMutex creates a new Mutex and sets the initial value to `init`. Call Mutex.Close to release resources.
func (Mutex[T]) Close ¶
func (mu Mutex[T]) Close() T
Close releases the Mutex's resources. Any future calls to Mutex.Use or Mutex.Replace will return an error. Close returns the guarded value.
type PreemptibleExclusiveAccess ¶
A PreemptibleExclusiveAccess function is equivalent to an ExclusiveAccess function except that it SHOULD yield the guarded value when receiving on the Priority channel if the received value is higher than its own.
type Priority ¶
type Priority uint
A Priority indicates the relative priority of a call to PriorityMutex.Use. Idiomatic usage is to treat higher values as being of greater importance; e.g. 0 for long-running background tasks and math.MaxUint for a time-critical preemption.
type PriorityMutex ¶
type PriorityMutex[T any] struct { // contains filtered or unexported fields }
A PriorityMutex is equivalent to a Mutex except that it is possible preempt the current holder of the lock. See PriorityMutex.Use for details.
func NewPriorityMutex ¶
func NewPriorityMutex[T any](init T) PriorityMutex[T]
NewPriorityMutex creates a new PriorityMutex and sets the initial value to `init`. Call PriorityMutex.Close to release resources.
func (PriorityMutex[T]) Close ¶
func (mu PriorityMutex[T]) Close() T
Close releases the PriorityMutex's resources. Any future calls to PriorityMutex.Use will return an error. Close returns the guarded value.
func (PriorityMutex[T]) Use ¶
func (mu PriorityMutex[T]) Use(ctx context.Context, priority Priority, fn PreemptibleExclusiveAccess[T]) error
Use calls `fn` with the guarded value. It is the equivalent of locking and then unlocking `mu`. The implementation of `fn` SHOULD receive values sent on the Priority channel that it takes as an argument, and return early if a higher-priority use is attempted, akin to honouring context.Context cancellation.
Source Files