throttle

Documentation

Overview

Package throttle allows calls to a function to be coalesced among multiple concurrent goroutines.

Index

• type Func
• type Set
  • func NewSet[Key comparable, T any]() *Set[Key, T]
  • func (s *Set[Key, T]) Call(ctx context.Context, key Key, run Func[T]) (T, error)
• type Throttle
  • func New[T any](run Func[T]) *Throttle[T]
  • func (t *Throttle[T]) Call(ctx context.Context) (T, error)

Types

type Func

type Func[T any] func(context.Context) (T, error)

Func is an alias for a function that can be managed by a Throttle.

type Set

type Set[Key comparable, T any] struct {
	// contains filtered or unexported fields
}

Set is a collection of Throttle values indexed by key. A zero value is ready for use, but must not be copied after first use.

func NewSet

func NewSet[Key comparable, T any]() *Set[Key, T]

NewSet constructs a new empty Set.

func (*Set[Key, T]) Call

func (s *Set[Key, T]) Call(ctx context.Context, key Key, run Func[T]) (T, error)

Call calls the throttle associated with key, constructing a new one if necessary. Call is safe for use by multiple concurrent goroutines.

All concurrent callers of Call with a given key share a single Throttle.

type Throttle

type Throttle[T any] struct {
	// contains filtered or unexported fields
}

A Throttle coalesces calls to a function so that all goroutines concurrently executing Throttle.Call share the result of a single execution of the function made by one of the participants.

A Throttle is initially idle. The first goroutine to execute Throttle.Call on an idle throttle begins a new session. All goroutines that call the throttle during an active session block until either:

• The context governing that call ends, in which case it reports a zero value and the error that ended the context.

• The goroutine executing the throttled function completes its call and reports a value and error, which is then shared among all the goroutines participating in the session.

If the execution of the throttled function ends because the context governing its calling goroutine ended, another waiting goroutine (if any) is woken up and given an oppoartunity to call the throttled function. Once all concurrent goroutines have returned, the throttle is once again idle, and the next caller will begin a new session.

func New

func New[T any](run Func[T]) *Throttle[T]

New constructs a new Throttle that executes run.

func (*Throttle[T]) Call

func (t *Throttle[T]) Call(ctx context.Context) (T, error)

Call invokes the function guarded by t. Call is safe for concurrent use by multiple goroutines.