subscriptions

Documentation

Overview

Package subscriptions provides support for managing subscriptions between components.

This package provides a simple subscription implementation with its Transmitter and Receiver types. Send messages with tx.Notify() and receive them with <-rx.Chan().

Subscriptions are keyed by the message type. Messages can be of any type, but that type must be unique within the agent codebase.

See the components documentation (doc/components) for more detailed usage information.

Warning

This package is not intended for high-bandwidth messaging such as metric samples. It use should be limited to events that occur on a per-second scale.

Index

• type Message
• type Receiver
  • func NewReceiver[M Message]() Receiver[M]
• type Transmitter
  • func (tx Transmitter[M]) Notify(message M)

Types

type Message

type Message interface{}

Message is the type of the message handled by a subscription point. It can be any type, but that type must be unique within the codebase. Do not use a basic type like `string` or `int` here.

type Receiver

type Receiver[M Message] struct {
	fx.Out

	Ch chan M `group:"subscriptions"`
}

Receiver defines a point where messages can be received.

A component wishing to receive messages should provide a value of this type from its Fx constructor, and later poll Receiver#Ch for messages.

A zero-valued Receiver is valid, but will not receive messages.

func NewReceiver

func NewReceiver[M Message]() Receiver[M]

NewReceiver creates a new Receiver.

The receiver's channel is buffered to allow concurrency, but with size 1. Components using a Receiver should poll the channel frequently to avoid blocking the transmitter.

type Transmitter

type Transmitter[M Message] struct {
	fx.In

	Chs []chan M `group:"subscriptions"`
}

Transmitter provides a way to send messages of a specific type.

A component wishing to transmit messages should include a value of this type in its dependencies.

It will be matched to zero or more Receivers.

func (Transmitter[M]) Notify

func (tx Transmitter[M]) Notify(message M)

Notify notifies all associated receivers of a new message.

If any receiver's channel is full, this method will block. If any receiver's channel is closed, this method will panic.