events

Documentation

Index

• Variables
• type Data
  • func NewData() Data
  • func (d Data) Clone() Data
• type Done
• type Emitter
  • func NewEmitter(l logger.Log) *Emitter
  • func (e *Emitter) Emit(evt string, d Data) Done
  • func (e *Emitter) EmitOnce(evt string, d Data) <-chan struct{}
  • func (e *Emitter) Off(evt string)
  • func (e *Emitter) On(evt string, h Handler)
  • func (e *Emitter) Once(evt string, h Handler)
  • func (e *Emitter) Stop()
• type Handler
• type HandlerFunc
  • func (hf HandlerFunc) Call(d Data) error
  • func (hf HandlerFunc) Source() interface{}

Variables

var ErrHalt = errors.New("intentional halt of event execution")

ErrHalt is a simple error used in place of just halting execution. Returning an error from a handlers Call will halt event execution, which may happen if a real error happens, or perhaps for some reason you just want to stop the event trigger. Therefore this error represents no particular error has ocurred but the event execution should be halted.

Types

type Data

type Data map[string]interface{}

Data is a generic map from strings to any values that can be used as a means to wrap a chunk of dynamic data and pass them to event handlers. Event data should contain data specific to the event being fired that would allow handlers to make actionable response to. Such as an "damage_taken" event might have a map containing "source" (who did the damage), "target" (who received the damage), and then data about the damage itself.

func NewData

func NewData() Data

NewData returns an empty map[string]interface{} wrapped in the Data type, as an easy way to seen event emissions with empty data (where nil would mean no data).

func (Data) Clone

func (d Data) Clone() Data

Clone will duplicate the data values and return a new data that is a deep copy of the original Data value.

type Done

type Done chan struct{}

Done is a channel designed to be closed when a task is finished. Data is never pushed over it.

type Emitter

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

Emitter represents a type capable of handling a list of callable actions to act on event data.

func NewEmitter

func NewEmitter(l logger.Log) *Emitter

NewEmitter generates a new event emitter with the given name used for logging purposes.

func (*Emitter) Emit

func (e *Emitter) Emit(evt string, d Data) Done

Emit will call all handlers and once handlers assigned to listen to the event as well as emitting a before:<event> and after:<event> before and after. This method is asyncronous and returns no values directly, failures get logged to the log target(s). Returns a readonly channel of struct{} (emtpy data) That is written two (once) when the emission has completed.

func (*Emitter) EmitOnce

func (e *Emitter) EmitOnce(evt string, d Data) <-chan struct{}

EmitOnce is similar to emit except it's designed to handle events intended that are only intended to be fired one time during the lifetime of the application. Any new handlers that are added for the one time emission are immediatley triggered with the data from the `EmitOnce` call.

func (*Emitter) Off

func (e *Emitter) Off(evt string)

Off will remove all handlers for the given event, including it's before and after handlers.

func (*Emitter) On

func (e *Emitter) On(evt string, h Handler)

On registers the handler for the given event. Events registered in this manner will be called every time this event is emitted.

func (*Emitter) Once

func (e *Emitter) Once(evt string, h Handler)

Once resgisters a handler for an event that will fire one time and then drop from the handler list. This is great for one time handlers, things that don't need to happen everytime the event is emitted.

func (*Emitter) Stop

func (e *Emitter) Stop()

Stop will mark the Emitter dead and prevent it receiving further events.

type Handler

type Handler interface {
	Call(Data) error
	Source() interface{}
}

Handler is a type with a Call function that accepts Data, and represents some callable type that wants to perform some action when an event is emitted. Handlers have a source value associated to them, this allows them to be uniquely bound -- avoiding a situation where the same object is bound twice.

type HandlerFunc

type HandlerFunc func(Data) error

HandlerFunc wraps a Go func in a painless way to match the events.Handler interface.

func (HandlerFunc) Call

func (hf HandlerFunc) Call(d Data) error

Call will just call the funtion the HandlerFunc type is wrapping and return it's results. This allows functions to fit the events.Handler interface painlessly.

func (HandlerFunc) Source

func (hf HandlerFunc) Source() interface{}

Source returns the pointer to the wrapped HandlerFunc value allowing for Go functions to be identified uniquely.