Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Handler ¶
type Handler[K comparable, V any] = func(*QueueHandle, K) (V, error)
Handler is the type for a Queue's handler function.
type KeyMutex ¶
type KeyMutex[K comparable] struct { // contains filtered or unexported fields }
KeyMutex provides mutual exclusion among operations targeting a given comparable key. The zero value is a valid KeyMutex with no locked keys.
A KeyMutex must not be copied after first use.
func (*KeyMutex[K]) Lock ¶
func (km *KeyMutex[K]) Lock(key K)
Lock blocks the calling goroutine until any other lock on the provided key is released.
func (*KeyMutex[K]) LockDetached ¶
func (km *KeyMutex[K]) LockDetached(qh *QueueHandle, key K)
LockDetached blocks the calling Handler until any other lock on the provided key is released. If the lock is not immediately available, LockDetached detaches the handler from its Queue while it waits for the lock, and reattaches before returning.
type Queue ¶
type Queue[K comparable, V any] struct { // contains filtered or unexported fields }
Queue is a concurrency-limited deduplicating work queue. It acts like a map that computes and caches the value for each requested key while limiting the number of computations in flight.
Each queue makes one or more concurrent calls to its Handler in new goroutines to compute a result for each requested key. It handles each key once regardless of the number of concurrent requests for that key, and caches and returns a single result for all requests.
The result for each key nominally consists of a value and an error, but may instead capture a panic or a call to runtime.Goexit. In the latter cases, the queue's Get* methods propagate the panic or Goexit to their caller.
Urgent Variants ¶
The Urgent variants of the queue's Get* methods push unhandled keys to the front of the work queue rather than the back.
The behavior of the Urgent variants is equivalent to that of the standard variants in any of the following cases:
- The results for all requested keys are already cached.
- Ample concurrency is available to handle the requested keys immediately.
- The requested keys were previously queued by a non-Urgent call. Urgent calls cannot "promote" these earlier non-Urgent calls.
All Variants ¶
The All variants of the queue's Get* methods coalesce the results for multiple keys into a single call. If every result consists of a value and non-nil error, the method returns a slice of values corresponding to the requested keys. Otherwise, it returns the first error or propagates the first panic or Goexit with respect to the order of the keys, without waiting for subsequent handlers to finish. To associate a result with a specific key or wait for all handlers, use the non-All variants instead.
When the queue's concurrency limit requires some keys to be queued for later handling, the All variants enqueue the unhandled keys in the order given, without interleaving keys from any other Get* call. However, a future Urgent call may interpose its unhandled key(s) between those enqueued by an earlier All call.
Concurrency Limits and Detaching ¶
Each queue is initialized with a limit on the number of goroutines that will concurrently handle new keys. However, QueueHandle.Detach permits a handler to increase the queue's effective concurrency limit for as long as it runs, or until it calls QueueHandle.Reattach. See QueueHandle for details.
func NewQueue ¶
func NewQueue[K comparable, V any](concurrency int, handle Handler[K, V]) *Queue[K, V]
NewQueue creates a Queue with the provided concurrency limit and handler.
If concurrency <= 0, the queue is created with an effectively unlimited concurrency of math.MaxInt.
func (*Queue[K, V]) Get ¶
Get returns the result or propagates the panic or Goexit for the provided key as described in the Queue documentation, blocking if necessary until the corresponding call to the queue's handler finishes.
func (*Queue[K, V]) GetAll ¶
GetAll coalesces the results for multiple keys as described in the "All Variants" section of the Queue documentation.
func (*Queue[K, V]) GetAllUrgent ¶
GetAllUrgent behaves like Queue.GetAll, but pushes new keys to the front of the queue as described in the "Urgent Variants" section of the Queue documentation.
type QueueHandle ¶
type QueueHandle struct {
// contains filtered or unexported fields
}
QueueHandle allows a Handler to interact with its parent queue.
func (*QueueHandle) Detach ¶
func (qh *QueueHandle) Detach() bool
Detach unbounds the calling Handler from the concurrency limit of the Queue that invoked it, allowing the queue to immediately handle other keys. It returns true if this call detached the handler, or false if the handler already detached.
QueueHandle.Reattach permits a detached handler to reestablish itself within the queue's concurrency limit ahead of the handling of new keys.
A typical use for detaching is to block on the availability of another resource. KeyMutex can facilitate this by detaching from a queue while awaiting a lock on a comparable key representing the resource.
func (*QueueHandle) Reattach ¶
func (qh *QueueHandle) Reattach()
Reattach blocks the calling Handler until it can execute within the concurrency limit of the Queue that invoked it. It has no effect if the handler is already attached.
type SetHandler ¶
type SetHandler[K comparable] = func(*QueueHandle, K) error
SetHandler is a type for a SetQueue's handler function.
type SetQueue ¶
type SetQueue[K comparable] = Queue[K, Empty]
SetQueue represents a Queue whose handlers return no meaningful value.
func NewSetQueue ¶
func NewSetQueue[K comparable](concurrency int, handle SetHandler[K]) *SetQueue[K]
NewSetQueue creates a SetQueue in a manner equivalent to how NewQueue creates a Queue.
type Stats ¶
type Stats struct {
// Done is the number of handled keys, whose results are computed and cached.
Done uint64
// Submitted is the number of keys whose results have been requested,
// including unhandled keys.
Submitted uint64
}
Stats conveys information about the keys and results in a Queue.
Source Files