core

type CommonMetricSampler struct {
	RTTListener         MetricSampleListener
	DropCounterListener MetricSampleListener
	InFlightListener    MetricSampleListener
}

type EmptyMetricRegistry struct{}

type EmptyMetricSampleListener struct{}

type Limit interface {
	// EstimatedLimit returns the current estimated limit.
	EstimatedLimit() int

	// NotifyOnChange will register a callback to receive notification whenever the limit is updated to a new value.
	//
	// consumer - the callback
	NotifyOnChange(consumer LimitChangeListener)

	// OnSample the concurrency limit using a new rtt sample.
	//
	// startTime - in epoch nanoseconds
	// rtt - round trip time of sample
	// inFlight - in flight observed count during the sample
	// didDrop - true if there was a timeout
	OnSample(startTime int64, rtt int64, inFlight int, didDrop bool)
}

type LimitChangeListener func(limit int)

type Limiter interface {
	// Acquire a token from the limiter.  Returns a nil listener if the limit has been exceeded.
	// If acquired the caller must call one of the Listener methods when the operation has been completed to release
	// the count.
	//
	// context - Context for the request. The context is used by advanced strategies such as LookupPartitionStrategy.
	Acquire(ctx context.Context) (listener Listener, ok bool)
}

type LimiterRegistry interface {
	// Get a limiter given a key.
	Get(key string) Limiter
}

type Listener interface {
	// OnSuccess is called as a notification that the operation succeeded and internally measured latency should be
	// used as an RTT sample.
	OnSuccess()
	// OnIgnore is called to indicate the operation failed before any meaningful RTT measurement could be made and
	// should be ignored to not introduce an artificially low RTT.
	OnIgnore()
	// OnDropped is called to indicate the request failed and was dropped due to being rejected by an external limit or
	// hitting a timeout.  Loss based Limit implementations will likely do an aggressive reducing in limit when this
	// happens.
	OnDropped()
}

type MeasurementInterface interface {
	// Add a single sample and update the internal state.
	// returns true if the internal state was updated, also return the current value.
	Add(value float64) (float64, bool)

	// Get the current value.
	Get() float64

	// Reset the internal state as if no samples were ever added.
	Reset()

	// Update will update the value given an operation function
	Update(operation func(value float64) float64)
}

type MetricRegistry interface {
	// RegisterDistribution will register a sample distribution.  Samples are added to the distribution via the returned
	// MetricSampleListener. Will reuse an existing MetricSampleListener if the distribution already exists.
	RegisterDistribution(ID string, tags ...string) MetricSampleListener

	// RegisterTiming will register a sample timing distribution.  Samples are added to the distribution via the
	// returned MetricSampleListener. Will reuse an existing MetricSampleListener if the distribution already exists.
	RegisterTiming(ID string, tags ...string) MetricSampleListener

	// RegisterCount will register a sample counter.  Samples are added to the counter via the returned
	// MetricSampleListener. Will reuse an existing MetricSampleListener if the counter already exists.
	RegisterCount(ID string, tags ...string) MetricSampleListener

	// RegisterGauge will register a gauge using the provided supplier.  The supplier will be polled whenever the gauge
	// value is flushed by the registry.
	RegisterGauge(ID string, supplier MetricSupplier, tags ...string)

	// Start will start the metric registry polling
	Start()

	// Stop will stop the metric registry polling
	Stop()
}

type MetricSampleListener interface {
	// AddSample will add a sample metric to the listener
	AddSample(value float64, tags ...string)
}

type MetricSupplier func() (value float64, ok bool)

type SampleWindow interface {
	// StartTimeNanoseconds returns the epoch start time in nanoseconds.
	StartTimeNanoseconds() int64
	// CandidateRTTNanoseconds returns the candidate RTT in the sample window. This is traditionally the minimum rtt.
	CandidateRTTNanoseconds() int64
	// AverageRTTNanoseconds returns the average RTT in the sample window.  Excludes timeouts and dropped rtt.
	AverageRTTNanoseconds() int64
	// MaxInFlight returns the maximum number of in-flight observed during the sample window.
	MaxInFlight() int
	// SampleCount is the number of observed RTTs in the sample window.
	SampleCount() int
	// DidDrop returns True if there was a timeout.
	DidDrop() bool
}

type StaticStrategyToken struct {
	// contains filtered or unexported fields
}

type Strategy interface {
	// TryAcquire will try to acquire a token from the limiter.
	// context Context of the request for partitioned limits.
	// returns not ok if limit is exceeded, or a StrategyToken that must be released when the operation completes.
	TryAcquire(ctx context.Context) (token StrategyToken, ok bool)

	// SetLimit will update the strategy with a new limit.
	SetLimit(limit int)
}

type StrategyToken interface {
	// IsAcquired returns true if acquired or false if limit has been reached.
	IsAcquired() bool
	// InFlightCount will return the number of pending requests.
	InFlightCount() int
	// Release the acquired token and decrement the current in-flight count.
	Release()
}