eventbus

README

eventbus

Straightforward EventBus for Go 1.18+

Go Version Support

Go 1.18+ is required, due to the use of generics

Project Status

Unlike some of my other projects that are used in production (eg. ensure for testing and erk for errors), this project is currently more on the experimental side. It has good test coverage, but I haven't actually built anything serious with it (yet!). So, please use at your own risk! Oh, and if you do use it for something serious, let me know how it works out!

Install

Library

$ go get github.com/JosiahWitt/eventbus

About

This package provides a straightforward concurrent, typed EventBus for Go 1.18+, supporting fanout, and in order, only once delivery.

Examples

Please see the examples directory for complete examples, such as the Simple Chat App.

Basic Usage

type Message struct { Body string }

bus := eventbus.New[*Message]()

// In one goroutine:
sub := bus.Subscribe("chatroom:123", "user:456")
for msg := range sub.Channel() {
  // Do something with msg
}
// Eventually...
sub.Unsubscribe()

// In another goroutine:
bus.Publish(&Message{Body: "Hello, World!"}, "chatroom:123", "user:789")
bus.Publish(&Message{Body: "Go is fun!"}, "chatroom:456", "user:456")
bus.Publish(&Message{Body: "Wordle 1/6"}, "chatroom:456", "user:789")
bus.Publish(&Message{Body: "Bonjour!"}, "chatroom:123", "user:456")

// sub will receive:
//  1. Hello, World!
//  2. Go is fun!
//  3. Bonjour!
// Each of those messages is published to one or both of `chatroom:123` and `user:456`.
//
// sub will not receive "Wordle 1/6", because that was published to neither `chatroom:123` nor `user:456`.

Documentation

Overview

Package eventbus provides a straightforward concurrent EventBus for Go 1.18+, supporting fanout, and in order, only once delivery.

Index

• Constants
• type Config
• type EventBus
  • func New[Event any]() *EventBus[Event]
  • func NewWithConfig[Event any](config *Config) *EventBus[Event]
  • func (b *EventBus[Event]) Publish(event Event, topicKeys ...string)
  • func (b *EventBus[Event]) Subscribe(topicKeys ...string) *Subscription[Event]
• type Subscription
  • func (sub *Subscription[Event]) Channel() <-chan Event
  • func (s *Subscription[Event]) Unsubscribe()

Constants

const DefaultBufferSize = 10

DefaultBufferSize for the subscription channels. Used when the BufferSize is not configured.

Types

type Config

type Config struct {
	// BufferSize for the subscription channels.
	// If not set or zero, it defaults to DefaultBufferSize.
	// If negative, it creates the channels with no buffer.
	BufferSize int
}

Config can be passed to NewWithConfig to customize the EventBus.

type EventBus

type EventBus[Event any] struct {
	// contains filtered or unexported fields
}

EventBus is a straightforward concurrent EventBus for Go 1.18+, supporting fanout, and in order, only once delivery.

It can be used by initializing a copy of the struct, or by calling the New or NewWithConfig functions.

func New

func New[Event any]() *EventBus[Event]

New creates a new EventBus.

func NewWithConfig

func NewWithConfig[Event any](config *Config) *EventBus[Event]

NewWithConfig creates a new customized EventBus.

func (*EventBus[Event]) Publish

func (b *EventBus[Event]) Publish(event Event, topicKeys ...string)

Publish sends the provided event to all of the listed topics. All subscriptions to those topics will be notified of the event.

func (*EventBus[Event]) Subscribe

func (b *EventBus[Event]) Subscribe(topicKeys ...string) *Subscription[Event]

Subscribe creates a new subscription to the listed topics. All events published to any of those topics will be sent to the subscription's channel.

If the same event is sent to multiple of the listed topics, the event will only be delivered once.

type Subscription

type Subscription[Event any] struct {
	// contains filtered or unexported fields
}

Subscription maintains subscriptions to multiple topics. Events are sent to the Channel().

func (*Subscription[Event]) Channel

func (sub *Subscription[Event]) Channel() <-chan Event

Channel exposes a read only view of the subscription's channel. All events published to the subscribed topics will be published to this channel.

If the same event is sent to multiple of the listed topics, the event will only be delivered once.

func (*Subscription[Event]) Unsubscribe

func (s *Subscription[Event]) Unsubscribe()

Unsubscribe closes the subscription to the topics. It also closes the subscription's channel.