fairqueuing

type EmptyHandler interface {
	// HandleEmpty is called to deliver the notification
	HandleEmpty()
}

type QueueSet interface {
	// SetConfiguration updates the configuration
	SetConfiguration(QueueSetConfig) error

	// Quiesce controls whether the QueueSet is operating normally or is quiescing.
	// A quiescing QueueSet drains as normal but does not admit any
	// new requests. Passing a non-nil handler means the system should
	// be quiescing, a nil handler means the system should operate
	// normally. A call to Wait while the system is quiescing
	// will be rebuffed by returning tryAnother=true. If all the
	// queues have no requests waiting nor executing while the system
	// is quiescing then the handler will eventually be called with no
	// locks held (even if the system becomes non-quiescing between the
	// triggering state and the required call).
	Quiesce(EmptyHandler)

	// Wait uses the given hashValue as the source of entropy as it
	// shuffle-shards a request into a queue and waits for a decision
	// on what to do with that request.  The descr1 and descr2 values
	// play no role in the logic but appear in log messages.  If
	// tryAnother==true at return then the QueueSet has become
	// undesirable and the client should try to find a different
	// QueueSet to use; execute and afterExecution are irrelevant in
	// this case.  Otherwise, if execute then the client should start
	// executing the request and, once the request finishes execution
	// or is canceled, call afterExecution().  Otherwise the client
	// should not execute the request and afterExecution is
	// irrelevant.
	Wait(ctx context.Context, hashValue uint64, descr1, descr2 interface{}) (tryAnother, execute bool, afterExecution func())
}

type QueueSetConfig struct {
	// Name is used to identify a queue set, allowing for descriptive information about its intended use
	Name string
	// ConcurrencyLimit is the maximum number of requests of this QueueSet that may be executing at a time
	ConcurrencyLimit int
	// DesiredNumQueues is the number of queues that the API says
	// should exist now.  This may be zero, in which case
	// QueueLengthLimit, HandSize, and RequestWaitLimit are ignored.
	DesiredNumQueues int
	// QueueLengthLimit is the maximum number of requests that may be waiting in a given queue at a time
	QueueLengthLimit int
	// HandSize is a parameter of shuffle sharding.  Upon arrival of a request, a queue is chosen by randomly
	// dealing a "hand" of this many queues and then picking one of minimum length.
	HandSize int
	// RequestWaitLimit is the maximum amount of time that a request may wait in a queue.
	// If, by the end of that time, the request has not been dispatched then it is rejected.
	RequestWaitLimit time.Duration
}

type QueueSetFactory interface {
	NewQueueSet(config QueueSetConfig) (QueueSet, error)
}