events

README

go-events

Simple global event signalling library for Go.

Documentation and example code can be found on GoDoc, or by browsing the example file.

Documentation

Overview

Package events provides an event notification and subscription system.

Index

• Variables
• func Announce(event Event)
• func Listen(prefix string) chan Event
• func Signal(tag string)
• type Event
  • func (e Event) String() string
• type Events
  • func New() Events

Examples

• Announce
• Listen
• Signal

Variables

var Verbosity = 0

Verbosity indicates how verbose the events library should be.

0 = no output (default)
1 = print event occurances
2 = print event subscriptions
3 = print event notifications

Functions

func Announce

func Announce(event Event)

Announce will register the global occurance of the given Event e, and pass it along for dispatch to interested listeners.

Example

This example shows how to include extra information with an Event beyond the Tag, and how this information can be extracted by the receiver.

Verbosity = 0

chn := Listen("example.")

go func() {
	Announce(Event{"example.hello", "world"})
	Announce(Event{"example.answer", 42})
}()

i := 0
for e := range chn {
	fmt.Println(e.Tag, e.Data)

	// Avoid listening forever
	i++
	if i == 2 {
		break
	}
}

Output:

example.hello world
example.answer 42

func Listen

func Listen(prefix string) chan Event

Listen will register interest in global Events whose Tag have the indicated prefix. The returned channel will receive any future matching Event.

To stop listening, simply close the channel. Attempting to send on the returned channel yields undefined behaviour. It is only writeable to allow closing.

Example

This example demonstrates how tag prefix matching works.

Verbosity = 0

chn := Listen("example.")

go func() {
	Signal("example.hello.world")
	Signal("example.hello.aliens")
}()

i := 0
for e := range chn {
	fmt.Println(e.Tag)

	// Avoid listening forever
	i++
	if i == 2 {
		break
	}
}

Output:

example.hello.world
example.hello.aliens

func Signal

func Signal(tag string)

Signal is a shortcut for announcing a global event with only a Tag, and no Data.

Example

This example shows the simples example of how to listen for, and announce, simple tagged events.

Verbosity = 0

chn := Listen("example.hello")

go func() {
	Signal("example.hello")
}()

e := <-chn
fmt.Println(e.Tag)

Output:

example.hello

Types

type Event

type Event struct {
	// Tag is a string describing the nature of the event. Listeners can
	// subscribe to prefixes of these tags.
	Tag string
	// Data allows arbitrary additional information to be dispatched along
	// with the event to any interested listeners.
	Data interface{}
}

Event represents a single occurance of some event in the underlying system.

func (Event) String

func (e Event) String() string

type Events

type Events interface {
	// Listen will register interest in Events whose Tag have the indicated
	// prefix.  The returned channel will receive any future matching
	// Event.
	//
	// To stop listening, simply close the channel. Attempting to send on
	// the returned channel yields undefined behaviour. It is only
	// writeable to allow closing.
	Listen(prefix string) chan Event
	// Announce will register the occurance of the given Event e, and pass
	// it along for dispatch to interested listeners.
	Announce(event Event)
	// Signal is a shortcut for announcing an event with only a Tag, and no
	// Data.
	Signal(tag string)
}

Events handles its own set of events.

func New

func New() Events

Construct a new, independent Events object.