event

README

Symfony Doge's Event

A set of reusable components for building a concurrent, message-oriented middleware in Go.

Installation

$ go get -u -d github.com/symfony-doge/event

Usage

DefaultListener

One subscriber, multiple publishers, no special routing.

DefaultListener acts like a subscriber that receives and process events (i.e. messages in context of pubsub pattern) from multiple publishers. It listens a channel wrapped by ROListenerSession. This implementation doesn't support any custom routing.

See example code snippet:

var consumeFunc event.ConsumeFunc = func (e event.Event) {
	fmt.Printf("An event has been received. Type: %d, Payload: %v\n", e.Type, e.Payload)
}

listenerSession := event.MustListen(consumeFunc)
defer listenerSession.Close()

var notifyChannel chan<- event.Event = listenerSession.NotifyChannel()

notifyChannel <- event.WithTypeAndPayload(1, "test payload 1")
notifyChannel <- event.WithTypeAndPayload(2, "test payload 2")
notifyChannel <- event.WithTypeAndPayload(3, "test payload 3")

Output will be:

An event has been received. Type: 1, Payload: test payload 1
An event has been received. Type: 2, Payload: test payload 2
An event has been received. Type: 3, Payload: test payload 3

See also

• agoalofalife/event — The Observer pattern implementation in Go.
• olebedev/emitter — Emits events in Go way, with wildcard, predicates, cancellation possibilities and many other good wins.
• leandro-lugaresi/hub — A fast Message/Event Hub using publish/subscribe pattern with support for topics like* rabbitMQ exchanges for Go applications.
• asaskevich/EventBus — Lightweight eventbus with async compatibility for Go.

Changelog

All notable changes to this project will be documented in CHANGELOG.md.

Documentation

Index

• type ConsumeFunc
• type DefaultListener
  • func DefaultListenerInstance() *DefaultListener
  • func NewDefaultListener() *DefaultListener
  • func (l *DefaultListener) Listen(fn ConsumeFunc) (ROListenerSession, error)
• type Event
  • func WithTypeAndPayload(t EventType, payload interface{}) Event
• type EventType
• type Events
• type Listener
• type ROListenerSession
  • func MustListen(fn ConsumeFunc) ROListenerSession
  • func (ls ROListenerSession) Close()
  • func (ls ROListenerSession) NotifyChannel() chan<- Event

Types

type ConsumeFunc

type ConsumeFunc func(Event)

ConsumeFunc is a callback signature for managing received events. It receives a read-only copy of an event from listening session.

type DefaultListener

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

DefaultListener encapsulates a common event listening logic (one subscriber to many publishers; a single channel will be used as a communication bridge) and supports multiple listening sessions.

func DefaultListenerInstance

func DefaultListenerInstance() *DefaultListener

DefaultListenerInstance returns a reference to the static DefaultListener instance.

func NewDefaultListener

func NewDefaultListener() *DefaultListener

NewDefaultListener returns a reference to the newly created DefaultListener instance.

func (*DefaultListener) Listen

func (l *DefaultListener) Listen(fn ConsumeFunc) (ROListenerSession, error)

Listen method starts and returns a new listening session with notification channel to which senders should push their events; stops listening when the notify channel becomes closed.

type Event

type Event struct {
	// The event type to decide receiver's logic.
	Type EventType

	// A custom data payload.
	Payload interface{}
}

Event represents a message in pubsub pattern with type information and a custom data payload.

func WithTypeAndPayload

func WithTypeAndPayload(t EventType, payload interface{}) Event

WithTypeAndPayload is a constructor that returns a new event with specified type and data payload.

type EventType

type EventType uint8

EventType is the category (or tag/marker) for events routing.

type Events

type Events []Event

Events is an alias to []Event

type Listener

type Listener interface {
	Listen(ConsumeFunc) (ROListenerSession, error)
}

Listener receives events (e.g. from workers) and calls a specified closure for processing. The Listen method returns a read-only listening session instance that exposes a communication channel between sender(s) and related event listener.

Usage example:

listenerSession, listenErr := eventListener.Listen(func(e Event) {})
if listenErr != nil {
    // Handle error.
}

var notifyChannel chan<- Event = listenerSession.NotifyChannel()
notifyChannel <- Event{}

listenerSession.Close()    // Use this method to close the channel safely.

type ROListenerSession

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

ROListenerSession is a read-only listener session that's used as a bridge between event listener and sender(s) (e.g. worker); a caller should pass the notification channel associated with listening session to the sender(s) to start communication via events.

func MustListen

func MustListen(fn ConsumeFunc) ROListenerSession

MustListen is a shortcut for starting a common event listener session. It will abort the program execution if any error occurs.

func (ROListenerSession) Close

func (ls ROListenerSession) Close()

Close method should be used to safely close the notification channel and stop the event listening session.

func (ROListenerSession) NotifyChannel

func (ls ROListenerSession) NotifyChannel() chan<- Event

NotifyChannel method returns a notification channel for sending events.