pollqueue

Documentation

Overview

Package pollqueue provides fair round-robin polling with a bounded manual priority lane for operator-triggered refreshes.

Index

• Constants
• type KeyFunc
• type Queue
  • func New[T any, V any](items []T, key KeyFunc[T]) *Queue[T, V]
  • func (q *Queue[T, V]) Enqueue(item T)
  • func (q *Queue[T, V]) EnqueueFront(item T)
  • func (q *Queue[T, V]) Latest(item T) (Result[T, V], bool)
  • func (q *Queue[T, V]) NextChunk(max int) []T
  • func (q *Queue[T, V]) Record(result Result[T, V])
• type Result

Constants

const (
	// StatusNotSampled marks values that are known to the queue but have not
	// returned from the poll loop yet.
	StatusNotSampled = "not_sampled"

	// MaxManualBurst is the number of front-lane emissions allowed before a
	// normal item must be considered when normal work is queued.
	MaxManualBurst = 1
)

Types

type KeyFunc

type KeyFunc[T any] func(T) string

KeyFunc returns the stable identity used for deduplication and latest-value lookups.

type Queue

type Queue[T any, V any] struct {
	// contains filtered or unexported fields
}

Queue rotates normal items in bulk-friendly chunks. EnqueueFront inserts a one-shot manual request ahead of normal rotation while preserving normal scheduler fairness.

func New

func New[T any, V any](items []T, key KeyFunc[T]) *Queue[T, V]

New creates a queue and seeds Latest for all initial items.

func (*Queue[T, V]) Enqueue

func (q *Queue[T, V]) Enqueue(item T)

Enqueue adds a normal round-robin item if it is not already queued.

func (*Queue[T, V]) EnqueueFront

func (q *Queue[T, V]) EnqueueFront(item T)

EnqueueFront adds a one-shot manual item to the front lane. Repeated manual requests for the same key collapse to one pending front-lane item.

func (*Queue[T, V]) Latest

func (q *Queue[T, V]) Latest(item T) (Result[T, V], bool)

Latest returns the freshest known result for item, including not-sampled placeholders seeded by Enqueue and EnqueueFront.

func (*Queue[T, V]) NextChunk

func (q *Queue[T, V]) NextChunk(max int) []T

NextChunk returns up to max items, giving front-lane requests priority while bounding consecutive manual emissions. The same key is emitted at most once per chunk.

func (*Queue[T, V]) Record

func (q *Queue[T, V]) Record(result Result[T, V])

Record stores a fresh result. A zero ObservedAt is replaced with time.Now.

type Result

type Result[T any, V any] struct {
	Item       T
	Value      V
	Status     string
	Error      string
	ObservedAt time.Time
}

Result is the freshest observed value for one queued item.