namedqueue

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 16, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

README

go-named-queue

Go implementation of the Rust named_queue crate's in-process named queue model. Queues have a fixed positive capacity and a message type fixed at creation. Multiple senders and receivers may share a queue; receivers compete for messages.

package main

import (
	"fmt"
	queue "github.com/wushilin/go-named-queue"
)

func main() {
	r := queue.NewRegistry()
	if err := queue.Create[string](r, "greetings", 16); err != nil {
		panic(err)
	}
	tx, _ := queue.AcquireSender[string](r, "greetings")
	rx, _ := queue.AcquireReceiver[string](r, "greetings")
	_ = tx.Send("hello")
	message, _ := rx.Recv()
	fmt.Println(message)
	_ = r.Shutdown("greetings")
}

Create creates a work-sharing queue: receivers compete, and each message is delivered to one receiver. CreateBroadcasting creates a broadcast queue: every receiver subscribed when a message is sent gets an independent delivery. Receivers acquired later start at the current tail. A broadcast send blocks when the bounded buffer is full until every subscribed receiver advances. Use CreateWithFullAction or CreateBroadcastingWithFullAction to select what happens when capacity is reached: FullBlock waits for space, FullDropOldest evicts the oldest pending message and enqueues the new one, and FullDropNewest silently discards the new message. Drop policies apply to Send and TrySend; TrySend with FullBlock returns ErrFull instead of waiting.

if err := queue.CreateBroadcasting[string](r, "events", 64); err != nil {
	panic(err)
}
tx, _ := queue.AcquireSender[string](r, "events")
a, _ := queue.AcquireReceiver[string](r, "events")
b, _ := queue.AcquireReceiver[string](r, "events")
_ = tx.Send("tick")
first, _ := a.Recv()
second, _ := b.Recv()
fmt.Println(first, second) // tick tick
a.Close()
b.Close()

Send and Recv block when the bounded queue is full or empty. TrySend and TryRecv are nonblocking and return ErrFull/ErrEmpty when unavailable.

Shutdown closes a queue: sends (including ones blocked at that moment) fail with ErrClosed, no new senders are issued, and shutting down again returns ErrClosed. Existing receivers drain the buffered messages and then receive ErrClosed. A shut-down work-sharing queue still admits new receivers while messages remain; a shut-down broadcast queue admits none, since a new subscription could never hold anything to drain. Destroy force-retires a queue and discards buffered messages. DestroyTake[T] retires a matching typed queue and returns its still-buffered messages.

Call Close on broadcast receivers when they are no longer needed so they no longer hold messages in the bounded buffer (with FullBlock, a forgotten receiver eventually blocks every sender). Close is idempotent, wakes a blocked Recv, and afterwards the receiver reports ErrClosed. Use NewRegistry to scope queues explicitly, or DefaultRegistry and the *Default helpers for process-wide queues. A registry's zero value is also usable; always pass a *QueueRegistry. Go's generic functions take the registry as an argument because Go does not support generic methods.

Differences from the Rust crate

  • Send errors do not hand the unsent value back; the caller still owns the value passed to Send.
  • A shut-down queue's name stays registered until the queue is drained and Destroy is called. Rust retires the entry automatically once the last receiver drains it; Go has no destructors to detect that.
  • Clone on a broadcast receiver creates an independent subscriber. In Rust, clones share one subscription and compete.
  • Broadcast queues default to FullBlock; the Rust default is DropOldest.
  • A broadcast send blocked on a full subscriber fails with ErrClosed when the queue is shut down, whereas Rust lets the in-flight send complete.
  • DestroyTake on a broadcast queue returns the still-buffered messages; Rust returns an empty list.
  • There is no async or context-aware API; Send/Recv cannot be cancelled.

Run go test -race ./... for the test suite and go test -bench . -benchmem for benchmarks.

Documentation

Overview

Package namedqueue provides named, typed, bounded in-process queues. Work-sharing queues deliver each message to one of the competing receivers; broadcast queues deliver each message to every subscribed receiver.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrExists            = errors.New("namedqueue: queue already exists")
	ErrNotFound          = errors.New("namedqueue: queue not found")
	ErrTypeMismatch      = errors.New("namedqueue: message type mismatch")
	ErrClosed            = errors.New("namedqueue: queue is closed")
	ErrFull              = errors.New("namedqueue: queue is full")
	ErrEmpty             = errors.New("namedqueue: queue is empty")
	ErrInvalidCapacity   = errors.New("namedqueue: capacity must be positive")
	ErrInvalidFullAction = errors.New("namedqueue: invalid full action")
)

Functions

func Create

func Create[T any](r *QueueRegistry, name string, capacity int) error

Create registers a bounded queue. Capacity must be positive.

func CreateBroadcasting

func CreateBroadcasting[T any](r *QueueRegistry, name string, capacity int) error

CreateBroadcasting registers a bounded queue where every subscribed receiver gets each message independently.

func CreateBroadcastingDefault

func CreateBroadcastingDefault[T any](name string, capacity int) error

func CreateBroadcastingDefaultWithFullAction

func CreateBroadcastingDefaultWithFullAction[T any](name string, capacity int, action FullAction) error

func CreateBroadcastingWithFullAction

func CreateBroadcastingWithFullAction[T any](r *QueueRegistry, name string, capacity int, action FullAction) error

CreateBroadcastingWithFullAction registers a broadcast queue with a full policy.

func CreateDefault

func CreateDefault[T any](name string, capacity int) error

func CreateDefaultWithFullAction

func CreateDefaultWithFullAction[T any](name string, capacity int, action FullAction) error

func CreateWithFullAction

func CreateWithFullAction[T any](r *QueueRegistry, name string, capacity int, action FullAction) error

CreateWithFullAction registers a bounded work-sharing queue with a full policy.

func Destroy

func Destroy(name string) error

func DestroyTake

func DestroyTake[T any](r *QueueRegistry, name string) ([]T, error)

DestroyTake force-retires a queue, returning all still-pending messages.

func DestroyTakeDefault

func DestroyTakeDefault[T any](name string) ([]T, error)

func Shutdown

func Shutdown(name string) error

Types

type FullAction

type FullAction uint8

FullAction selects what Send does when a bounded queue is full.

const (
	// FullBlock waits until receivers make space.
	FullBlock FullAction = iota
	// FullDropOldest evicts the oldest pending message and enqueues the new one.
	FullDropOldest
	// FullDropNewest discards the message being sent and returns success.
	FullDropNewest
)

type QueueRegistry

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

QueueRegistry owns named queues. Its zero value is ready to use; handles made with Clone share the same registry. Always pass a *QueueRegistry around; a QueueRegistry value must not be copied.

func DefaultRegistry

func DefaultRegistry() *QueueRegistry

func NewRegistry

func NewRegistry() *QueueRegistry

func (*QueueRegistry) Clone

func (r *QueueRegistry) Clone() *QueueRegistry

Clone returns another registry handle sharing the same queues.

func (*QueueRegistry) Destroy

func (r *QueueRegistry) Destroy(name string) error

Destroy force-retires a queue and discards pending messages.

func (*QueueRegistry) Shutdown

func (r *QueueRegistry) Shutdown(name string) error

Shutdown rejects future sends and allows receivers to drain pending messages. Shutting down a queue that is already shut down returns ErrClosed.

func (*QueueRegistry) State

func (r *QueueRegistry) State(name string) (State, error)

State returns the queue's open/closed state and number of pending messages.

type Receiver

type Receiver[T any] struct {
	// contains filtered or unexported fields
}

Receiver is a consumer handle. Copies compete for messages.

func AcquireDefaultReceiver

func AcquireDefaultReceiver[T any](name string) (*Receiver[T], error)

func AcquireReceiver

func AcquireReceiver[T any](r *QueueRegistry, name string) (*Receiver[T], error)

AcquireReceiver returns a consumer handle for a registered queue. A shut-down work-sharing queue still admits receivers while messages remain to be drained; a shut-down broadcast queue admits none.

func (*Receiver[T]) Clone

func (r *Receiver[T]) Clone() *Receiver[T]

func (*Receiver[T]) Close

func (r *Receiver[T]) Close()

Close unsubscribes this receiver. Close broadcast receivers when they are no longer needed.

func (*Receiver[T]) Recv

func (r *Receiver[T]) Recv() (T, error)

func (*Receiver[T]) TryRecv

func (r *Receiver[T]) TryRecv() (T, error)

type Sender

type Sender[T any] struct {
	// contains filtered or unexported fields
}

Sender is a producer handle. Copies of a sender share the same queue.

func AcquireDefaultSender

func AcquireDefaultSender[T any](name string) (*Sender[T], error)

func AcquireSender

func AcquireSender[T any](r *QueueRegistry, name string) (*Sender[T], error)

AcquireSender returns a producer handle for a registered queue. A shut-down queue issues no new senders.

func (*Sender[T]) Clone

func (s *Sender[T]) Clone() *Sender[T]

func (*Sender[T]) Send

func (s *Sender[T]) Send(v T) error

func (*Sender[T]) TrySend

func (s *Sender[T]) TrySend(v T) error

type State

type State struct {
	Open    bool
	Pending int
}

State is a point-in-time queue lifecycle snapshot.

func QueueState

func QueueState(name string) (State, error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL