prioritywaitqueue

README

go-prioritywaitqueue

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

Install

go get github.com/rvagg/go-prioritywaitqueue

Usage

// global setup
var workerCmp prioritywaitqueue.ComparePriority[*worker] = func(a *worker, b *worker) bool {
	return a.id < b.id
}
queue := prioritywaitqueue.New(workerCmp)

// per-goroutine use
func (w *worker) doSomething() {
  done := w.queue.Wait(w) // will block until this goroutine is allowed to run
  defer done() // signal that the work has completed and another goroutine can run

  // ... work
}

License

Copyright © 2022 Rod Vagg

Licensed under either of

• Apache 2.0, (LICENSE-APACHE / http://www.apache.org/licenses/LICENSE-2.0)
• MIT (LICENSE-MIT / http://opensource.org/licenses/MIT)

Documentation

Overview

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

Index

• type ComparePriority
• 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{}](cmp ComparePriority[T], options ...Option[T]) PriorityWaitQueue[T]

Types

type ComparePriority

type ComparePriority[T interface{}] func(a T, b T) bool

ComparePriority should return true if a has a higher priority, and therefore should run, BEFORE b.

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()
}

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{}](cmp ComparePriority[T], options ...Option[T]) PriorityWaitQueue[T]

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