prioritywaitqueue

Documentation

Overview

Package prioritywaitqueue implements a blocking queue for prioritised coordination of goroutine execution.

Index

• type Chooser
• type Option
  • func WithClock[T interface{}](clock clock.Clock) Option[T]
  • func WithInitialPause[T interface{}](duration time.Duration) Option[T]
• type PriorityWaitQueue
  • func New[T interface{}](choose Chooser[T], options ...Option[T]) PriorityWaitQueue[T]

Types

type Chooser

type Chooser[T interface{}] func(waiters []T) int

Chooser should return the index of the highest-priority item in the list of waiters. The list of waiters is guaranteed to be > 1 in length.

type Option

type Option[T interface{}] func(PriorityWaitQueue[T])

func WithClock

func WithClock[T interface{}](clock clock.Clock) Option[T]

WithClock sets the clock to use for the PriorityWaitQueue. This is useful for testing.

func WithInitialPause

func WithInitialPause[T interface{}](duration time.Duration) Option[T]

WithInitialPause sets an initial pause for the first call to Wait() on the PriorityWaitQueue. This is useful if you want to allow goroutines to queue up before any of them are allowed to run. A short pause will mean that the initial first-in-first-run behaviour is overridden, where the first goroutine may have to compete with others before getting to run.

type PriorityWaitQueue

type PriorityWaitQueue[T interface{}] interface {
	// Wait is called with with a value that can be prioritised in comparison to
	// other values of the same type. Returns a "done" function that MUST be
	// called when the work to be performed. The call to Wait will block until
	// there are other running goroutines that have also called Wait and not yet
	// called their "done" function.
	//
	// It is up to the caller to handle context cancellation, goroutines should
	// check for themselves when Wait() returns and immediately call done() if
	// a context has cancelled in order to clean up all running goroutines.
	Wait(waitWith T) func()

	// InitialPauseDone returns once the initial pause has been completed and
	// will block until then. If an initial pause was not set, or has already
	// completed, this will return immediately. Setting block to false will make
	// this function return immediately with a bool indicating whether the initial
	// pause was completed. This is useful for testing.
	InitialPauseDone(block bool) bool
}

PriorityWaitQueue is a blocking queue for coordinating goroutines, providing a gating mechanism such that only one goroutine may run at a time, where the goroutine allowed to run is chosen based on a priority comparison function.

func New

func New[T interface{}](choose Chooser[T], options ...Option[T]) PriorityWaitQueue[T]

New creates a new PriorityWaitQueue with the provided ComparePriority function for type T.