requestman

type DistancerContainer struct {
	D mathx.Distancer
	// TODO: Check performance. As of now, each call to Distancer() method does
	// a time.Now() call; the alternative is to have a bool in addition, as that
	// is cheaper. But that would also require a sync.RWMutes due to how this
	// will be used concurrently in the knnc pkg.
	Expires time.Time
}

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

type KNNArgs struct {
	// Namespace is used to group search spaces together, based on logical
	// meaning, but also for having uniform vector dimensions.
	Namespace string
	// Priority specifies how important a KNN query is -- higher is better.
	// It influences the number of goroutines used, though not necessarily
	// a one-to-one mapping. Must be > 0.
	Priority int
	// QueryVec is used for similarity searching. Must not be nil, with a
	// length of > 0. Also, make sure the dimension is appropriate for the
	// KNNArgs.namespace field.
	QueryVec []float64
	// KNNMethod specifies the distance function used for the query.
	// KNNMethod.Ok() must return true.
	KNNMethod KNNMethod
	// Ascending plays a role with ordering _and_ the meaning is dependent
	// somewhat on the KNNArgs.KNNMethod field.
	//
	// Euclidean distance, for instance, works on the principle that lower
	// is better, so then it would make sense to have Ascending=true for
	// KNN. For K-furthest-neighs, Ascending=false has to be used, as that
	// would reverse the order. The exact opposite is true for Cosine simi.
	Ascending bool
	// K is the K in KNN. However, the actual result might be less than this
	// number, for multiple reasons. One of them is that there simply might
	// not be enough data to search. Another reason is that the underlying
	// knn pkg uses a few optimization tricks to trade accuracy for speed,
	// the reamainding fields below give more documentation.
	K int
	// Extent specifies the extent of a search, in a range (0, 1]. For
	// example, 0.5 will search half the search space. This is used to
	// trade accuracy for speed.
	Extent float64
	// Accept is another optimization trick; the search will be aborted
	// when there are KNNArgs.K results with better than KNNArgs.Accept
	// accuracy.
	Accept float64
	// Reject is another optimization trick; the knn search pipeline will
	// drop all values worse than this fairly early on, such that the
	// load on downstream processes/pipes gets alleviated. Do note that
	// this is evaluated before KNNArgs.Accept, so Accept can be cancelled
	// out by Reject.
	Reject float64
	// TTL specifies the deadline for a knn request. The pipeline will
	// start shutting down for this request after the deadline, but it
	// is a good idea to cancel it manually. After this duration, the
	// best-found results are given. Must be > 0.
	TTL time.Duration

	// Monitor true will register the KNN request (and results).
	Monitor bool
}

type KNNEnqueueResult struct {
	// Pipe is the destination of a KNN request/query.
	Pipe chan knnc.ScoreItems
	// Cancel can be used to cancel a request. This is done automatically
	// with KNNArgs.TTL when making a query, but the cancel func should
	// be called nontheless.
	Cancel context.CancelFunc
}

type KNNMethod int

type KNNMonItemAvg struct {
	Created time.Time     // Start of recording.
	Span    time.Duration // Recording duration.

	N               int           // Number of recorded requests (including fails).
	NFailed         int           // Number of (completely) failed requests.
	AvgLatency      time.Duration // Average latency of all requests.
	AvgScore        float64       // Average score for all requests.
	AvgScoreNoFails float64       // Same as AvgScore but without fails.
	AvgSatisfaction float64       // Success ratio (got n / want n).
	// contains filtered or unexported fields
}

type NewHandleArgs struct {
	// NewSearchSpaceArgs keeps instructions for how to create new search spaces.
	// This is done 'occasionally' on Handle.AddData(...). For more details, see
	// documentation for the knnc pkg (particularly for T SearchSpaces).
	NewSearchSpaceArgs knnc.NewSearchSpacesArgs
	// NewLatencyTrackerArgs keeps instructions for how to create new latency
	// trackers. This is used for the KNN request queue in T Handle, as well as
	// for each new namespaced (KNN) search space.
	NewLatencyTrackerArgs timex.EventTrackerConfig

	// KNNQueueBuf specifies the buffer for the KNN request queue in T Handle.
	KNNQueueBuf int
	// KNNQueueMaxConcurrent specifies the max number of _parent_ goroutines
	// available for the KNN request queue in T Handle. In other words, it
	// specifies how many KNN requests can be processed concurrently -- though
	// each KNN request can use multiple goroutines individually.
	KNNQueueMaxConcurrent int

	// Ctx is used to stop the KNN request queue. It will also be used to stop
	// the maintanence loop for each namespaced (KNN) search space (for more
	// info about this, see docs for T SearchSpaces of pkg/knnc).
	Ctx context.Context

	// NewKNNMonitorArgs keeps instructions for how to make a new monitor.
	// This includes same args as timex.NewLatencyArgs, as the internal
	// data structure works the same way.
	NewKNNMonitorArgs timex.EventTrackerConfig
}