type DispatchingConfig struct {
	// ConcurrencyLimit is the maximum number of requests of this QueueSet that may be executing at a time
	ConcurrencyLimit int
}

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

type QueueSet interface {
	// BeginConfigChange starts the two-step process of updating
	// the configuration.  No change is made until Complete is
	// called.  If `C := X.BeginConstruction(q)` then
	// `C.Complete(d)` returns the same value `X`.  If the
	// QueuingConfig's DesiredNumQueues field is zero then the other
	// queuing-specific config parameters are not changed, so that the
	// queues continue draining as before.
	BeginConfigChange(QueuingConfig) (QueueSetCompleter, 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).  In Go
	// Memory Model terms, the triggering state happens before the
	// call to the EmptyHandler.
	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.  In the terms of the Go Memory Model, there was a
	// call to Quiesce with a non-nil handler that happened before
	// this return from Wait.  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.  Canceling the context while the
	// request is waiting in its queue will cut short that wait and
	// cause a return with tryAnother and execute both false; later
	// cancellations are the caller's problem.
	Wait(ctx context.Context, hashValue uint64, descr1, descr2 interface{}) (tryAnother, execute bool, afterExecution func())
}

type QueueSetCompleter interface {
	// Complete returns a QueueSet configured by the given
	// dispatching configuration.
	Complete(DispatchingConfig) QueueSet
}

type QueueSetFactory interface {
	// BeginConstruction does the first phase of creating a QueueSet
	BeginConstruction(QueuingConfig) (QueueSetCompleter, error)
}

type QueuingConfig struct {
	// Name is used to identify a queue set, allowing for descriptive information about its intended use
	Name string

	// 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
}