queue

README

internal/queue

Goroutine-safe in-memory ticket store.

Responsibility

Hold pending tickets in insertion order so the matchmaker can take a stable snapshot, attempt matches against it, and remove only the tickets actually consumed. Cancellation by external producers happens through the same store.

Contents

• Queue — the store. Construct with New().
• Enqueue(t core.Ticket) error — append, rejecting duplicate IDs with ErrDuplicateTicket.
• Cancel(id string) error — remove by ID, returning ErrUnknownTicket if the ID isn't present.
• Remove(ids []string) — bulk-delete used by the matchmaker after forming a match. Unknown IDs are ignored.
• Snapshot() []core.Ticket — copy of the queue contents in insertion order; safe to mutate by the caller.
• Len() int — number of pending tickets.

Design notes

• All mutating methods take a single mutex. The expected workload is low-contention (a handful of producers, one Tick goroutine), so a simpler design beats anything fancier here.
• Snapshot allocates a fresh slice every call so the matchmaker can iterate without holding the lock — important because rule evaluation during a tick is the slow part.
• This package is deliberately scope-limited. Persistence, expiry, prioritisation, and TTLs all belong elsewhere: the matchmaker layer decides when a ticket is "too old", not the queue.
• The queue only ever holds tickets in StatusQueued. Once a match candidate is formed, the matchmaker Removes the tickets from here and tracks their subsequent status (REQUIRES_ACCEPTANCE, PLACING, …) outside the queue. Ticket-status bookkeeping is not this package's concern.

Documentation

Overview

Package queue is the in-memory ticket store used by the matchmaker. It preserves insertion order and is safe for concurrent Enqueue / Cancel / Snapshot calls.

Index

• Variables
• type Queue
  • func New() *Queue
  • func (q *Queue) Cancel(id string) error
  • func (q *Queue) Enqueue(t core.Ticket) error
  • func (q *Queue) Len() int
  • func (q *Queue) Remove(ids []string)
  • func (q *Queue) Snapshot() []core.Ticket

Variables

var ErrDuplicateTicket = errors.New("queue: duplicate ticket id")

ErrDuplicateTicket is returned by Enqueue when a ticket with the same ID is already in the queue.

var ErrUnknownTicket = errors.New("queue: unknown ticket id")

ErrUnknownTicket is returned by Cancel when the ticket id is not present.

Types

type Queue

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

Queue is a goroutine-safe ordered ticket store.

func New

func New() *Queue

New returns an empty Queue.

func (*Queue) Cancel

func (q *Queue) Cancel(id string) error

Cancel removes the ticket with id. ErrUnknownTicket is returned if absent.

func (*Queue) Enqueue

func (q *Queue) Enqueue(t core.Ticket) error

Enqueue adds t. ErrDuplicateTicket is returned if the id is already known.

func (*Queue) Len

func (q *Queue) Len() int

Len returns the number of pending tickets.

func (*Queue) Remove

func (q *Queue) Remove(ids []string)

Remove deletes a set of ids (used by the matchmaker after forming a match). Unknown ids are silently ignored.

func (*Queue) Snapshot

func (q *Queue) Snapshot() []core.Ticket

Snapshot returns the tickets in enqueue order. The returned slice is a copy safe for the caller to mutate.