Go Event Bus

An event bus to react to all the things.

Installation

go get github.com/io-da/event

Overview

1. Events
2. Handlers
3. Error Handlers
4. The Bus
   1. Tweaking Performance
   2. Shutting Down
   3. Available Errors
5. Benchmarks
6. Examples

Introduction

This library is intended for anyone looking to emit events in their application. And it achieves this objective using an event bus architecture.
The Bus will use workers (goroutines) to attempt handling the events in non-blocking manner.
Clean and simple codebase. No reflection, no closures.

Getting Started

Events

This type is used to provide a consistent identity solution for both events and topics.

type Identifier int64

Events are any type that implements the Event interface. Ideally they should contain immutable data.

type Event interface {
    Identifier() Identifier
}

An event may optionally implement the Topic interface. If it does, then it will be handled within that topic.

type Topic interface {
    Event
    Topic() Identifier
}

Any event emitted within the same topic is guaranteed to be handled respecting their order of emission.
However, this order is not guaranteed across different topics.
A topic is just an Identifier (int64), the event bus will take care of the rest.
Events that do not implement the Topic interface will be considered concurrent.
The Bus takes advantage of additional workers (goroutines) to handle concurrent events faster, but their emission order will not be respected.

Handlers

Handlers are any type that implements the Handler interface. Handlers must be instantiated and provided to the bus on initialization.

type Handler interface {
    Handle(evt Event) error
}

Error Handlers

Error handlers are any type that implements the ErrorHandler interface. Error handlers are optional (but advised) and provided to the bus using the bus.ErrorHandlers function.

type ErrorHandler interface {
    Handle(evt Event, err error)
}

Any time an error occurs within the bus, it will be passed on to the error handlers. This strategy can be used for decoupled error handling.

The Bus

Bus is the struct that will be used to emit all the application's events.
The Bus should be instantiated and initialized on application startup. The initialization is separated from the instantiation for dependency injection purposes.
The application should instantiate the Bus once and then use it's reference in all the places that will be emitting events.
The order in which the handlers are provided to the Bus is always respected.

Tweaking Performance

For applications that take advantage of concurrent events, the number of concurrent workers can be adjusted.

bus.SetConcurrentWorkerPoolSize(10)

If used, this function must be called before the Bus is initialized. And it specifies the number of goroutines used to handle concurrent events.
In some scenarios increasing the value can drastically improve performance.
It defaults to the value returned by runtime.GOMAXPROCS(0).

When aware of the total amount of different topics available in the application. Then that value should be provided with this function.

bus.SetTopicsCapacity(10)

If used, this function must be called before the Bus is initialized.
It defaults to 10.

The buffer size of topics can also be adjusted.
Depending on the use case, this value may greatly impact performance.

bus.SetTopicBuffer(100)

If used, this function must be called before the Bus is initialized.
It defaults to 100.

Shutting Down

The Bus also provides a shutdown function that attempts to gracefully stop the event bus and all its routines.

bus.Shutdown()

This function will block until the bus is fully stopped.

Available Errors

Below is a list of errors that can occur when calling bus.Emit.

event.ErrorInvalidEvent  
event.ErrorEventBusNotInitialized
event.ErrorEventBusIsShuttingDown

Benchmarks

All the benchmarks are performed against batches of 1 million events.
All the ordered events belong to the same topic.
All the benchmarks contain some overhead due to the usage of sync.WaitGroup.

Benchmarks with simulated handler behavior

The event handlers calculate the fibonacci of 1000 for simulation purposes.

Benchmark Type	Time
Ordered Events	17355 ns/op
Concurrent Events	2565 ns/op

Examples

An optional constants list of event and topic identifiers (idiomatic enum) for consistency

const (
   Unidentified Identifier = iota
   FooEvent
   BarEvent
)

const (
   Unidentified Identifier = iota
   BarTopic
)

Example Events

A simple struct event.

type Foo struct {
    bar string
}
func (*Foo) Identifier() Identifier {
    return FooEvent
}

A string event that implements the Topic interface.

type Bar string
func (Bar) Topic() Identifier { return BarTopic }
func (Bar) Identifier() Identifier {
    return BarEvent
}

Example Handlers

An event handler that logs every event emitted.

type LoggerHandler struct {
}

func (hdl *LoggerHandler) Handle(evt Event) error {
    log.Printf("event %T emitted", evt)
    return nil
}

An event handler that listens to multiple event types.

type FooBarHandler struct {
}

func (hdl *FooBarHandler) Handle(evt Event) error {
    // a convenient way to assert multiple event types.
    switch evt := evt.(type) {
    case *Foo, Bar:
        // handler logic
    }
    return nil
}

Putting it together

Initialization and usage of the exemplified events and handlers

import (
    "github.com/io-da/event"
)

func main() {
    // instantiate the bus (returns *event.Bus)
    bus := event.NewBus()
    
    // initialize the bus with all the application's event handlers
    bus.Initialize(
    	// this handler will always be executed first
        &LoggerHandler{},
        // this one second
        &FooBarHandler{},
    )
    
    // emit events
    bus.Emit(&Foo{})
    bus.Emit(Bar("bar"))
}

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT