Documentation
¶
Overview ¶
Package events implements a simple callback-based event emitter with event filtering and one-time event handling capabilities.
Although you can create individual events.Emitter structs, it's more common to use the default emitter and top-level package API to emit and listen for application-wide events.
The events.Listen and events.Unlisten methods work with events.Listener structs that wrap the event handling callback. This lets you define several ways to filter for certain events, as well as specify it as a one-off listener that only gets called once.
Events emitted need to implement the events.Event interface, allowing arbitrary event value types as long as they implement the interface. This helps identify them as an event and identifies the name of the event, useful for further type assertions.
Handler callbacks need to be aware they are called synchronously and should perform any time-intensive operation asynchronously. Otherwise it will block the call to Emit, which shouldn't have to be called asynchronously.
Example (Basic) ¶
Basic example shows a basic event listener and emitting an event struct
package main
import (
"fmt"
"time"
"github.com/gliderlabs/comlab/pkg/events"
)
// exported constant allows other packages to refer to event by name
const EventLogin = "login"
// struct used as an event with fields specific to event
type LoginEvent struct {
Username string
Time time.Time
}
// implementing Event interface makes it an event
func (e LoginEvent) EventName() string {
return EventLogin
}
// Basic example shows a basic event listener and emitting an event struct
func main() {
// any package can set up a listener
events.Listen(&events.Listener{
EventName: EventLogin,
Handler: func(e events.Event) {
login, ok := e.(*LoginEvent)
if !ok {
return
}
fmt.Println("Hello,", login.Username)
},
})
// any package can emit the event,
// though it's usually the package that owns the event
events.Emit(&LoginEvent{
Username: "progrium",
Time: time.Now(),
})
}
Output: Hello, progrium
Example (Signal) ¶
Signal example shows using Signal type as event, which has no payload but its name
package main
import (
"fmt"
"github.com/gliderlabs/comlab/pkg/events"
)
const SignalHello = "Hello world"
// Signal example shows using Signal type as event, which has no payload but its name
func main() {
events.Listen(&events.Listener{
EventName: SignalHello,
Handler: func(e events.Event) {
fmt.Println(e)
},
})
events.Emit(events.Signal(SignalHello))
}
Output: Hello world
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Emit ¶
func Emit(event Event)
Emit triggers the handlers of listeners that match the event, passing the event to them.
If it triggers a listener with Once set to true, the listener will be removed after triggering.
Types ¶
type Emitter ¶
type Emitter struct {
// contains filtered or unexported fields
}
Emitter is a collection of Listeners that you can Emit events to
type Listener ¶
type Listener struct {
// If not empty, only receive events with this name
EventName string
// If true, will fire only once and then listener will be removed
Once bool
// If not nil, a callback to determine if handler will be called
Filter func(Event) bool
// Callback to handle event
Handler func(Event)
}
Listener wraps an event handler callback, optionally specifying how it receives events from an Emitter
Source Files