events

README

Simple EventEmmiter for Go Programming Language. Inspired by Nodejs EventEmitter. For Generics support please wait until go1.18 stable is released, until then switch to dev branch instead.

Overview

New() EventEmmiter // New returns a new, empty, EventEmmiter

// AddListener is an alias for .On(eventName, listener).
AddListener(EventName, ...Listener)
// Emit fires a particular event,
// Synchronously calls each of the listeners registered for the event named
// eventName, in the order they were registered,
// passing the supplied arguments to each.
Emit(EventName, ...interface{})
// EventNames returns an array listing the events for which the emitter has registered listeners.
// The values in the array will be strings.
EventNames() []EventName
// GetMaxListeners returns the max listeners for this emmiter
// see SetMaxListeners
GetMaxListeners() int
// ListenerCount returns the length of all registered listeners to a particular event
ListenerCount(EventName) int
// Listeners returns a copy of the array of listeners for the event named eventName.
Listeners(EventName) []Listener
// On registers a particular listener for an event, func receiver parameter(s) is/are optional
On(EventName, ...Listener)
// Once adds a one time listener function for the event named eventName.
// The next time eventName is triggered, this listener is removed and then invoked.
Once(EventName, ...Listener)
// RemoveAllListeners removes all listeners, or those of the specified eventName.
// Note that it will remove the event itself.
// Returns an indicator if event and listeners were found before the remove.
RemoveAllListeners(EventName) bool
// Clear removes all events and all listeners, restores Events to an empty value
Clear()
// SetMaxListeners obviously this function allows the MaxListeners
// to be decrease or increase. Set to zero for unlimited
SetMaxListeners(int)
// Len returns the length of all registered events
Len() int

import "github.com/kataras/go-events"

// initialize a new EventEmmiter to use
e := events.New()

// register an event with name "my_event" and one listener
e.On("my_event", func(payload ...interface{}) {
  message := payload[0].(string)
  print(message) // prints "this is my payload"
})

// fire the 'my_event' event
e.Emit("my_event", "this is my payload")

Default/global EventEmmiter

// register an event with name "my_event" and one listener to the global(package level) default EventEmmiter
events.On("my_event", func(payload ...interface{}) {
  message := payload[0].(string)
  print(message) // prints "this is my payload"
})

// fire the 'my_event' event
events.Emit("my_event", "this is my payload")

Remove an event

events.On("my_event", func(payload ...interface{}) {
  // first listener...
},func (payload ...interface{}){
  // second listener...
})

println(events.Len()) // prints 1
println(events.ListenerCount("my_event")) // prints 2

// Remove our event, when/if we don't need this or we want to clear all of its listeners
events.RemoveAllListeners("my_event")

println(events.Len()) // prints 0
println(events.ListenerCount("my_event")) // prints 0

Installation

The only requirement is the Go Programming Language.

$ go get -u github.com/kataras/go-events

FAQ

Explore these questions or navigate to the [community chat][Chat].

Versioning

Current: v0.0.3

Read more about Semantic Versioning 2.0.0

• http://semver.org/
• https://en.wikipedia.org/wiki/Software_versioning
• https://wiki.debian.org/UpstreamGuide#Releases_and_Versions

Contributing

If you are interested in contributing to the go-events project, please prepare a PR.

License

This project is licensed under the MIT License.

License can be found here.

Documentation

Overview

Package events provides simple EventEmmiter support for Go Programming Language

Index

• Constants
• func AddListener(evt EventName, listener ...Listener)
• func Clear()
• func Emit(evt EventName, data ...interface{})
• func GetMaxListeners() int
• func Len() int
• func ListenerCount(evt EventName) int
• func On(evt EventName, listener ...Listener)
• func Once(evt EventName, listener ...Listener)
• func RemoveAllListeners(evt EventName) bool
• func SetMaxListeners(n int)
• type EventEmmiter
  • func New() EventEmmiter
• type EventName
  • func EventNames() []EventName
• type Events
  • func (e Events) CopyTo(emmiter EventEmmiter)
• type Listener
  • func Listeners(evt EventName) []Listener

Examples

• Events

Constants

const (
	// Version current version number
	Version = "0.0.3"
	// DefaultMaxListeners is the number of max listeners per event
	// default EventEmitters will print a warning if more than x listeners are
	// added to it. This is a useful default which helps finding memory leaks.
	// Defaults to 0, which means unlimited
	DefaultMaxListeners = 0

	// EnableWarning prints a warning when trying to add an event which it's len is equal to the maxListeners
	// Defaults to false, which means it does not prints a warning
	EnableWarning = false
)

Functions

func AddListener

func AddListener(evt EventName, listener ...Listener)

AddListener is an alias for .On(eventName, listener).

func Clear

func Clear()

Clear removes all events and all listeners, restores Events to an empty value

func Emit

func Emit(evt EventName, data ...interface{})

Emit fires a particular event, Synchronously calls each of the listeners registered for the event named eventName, in the order they were registered, passing the supplied arguments to each.

func GetMaxListeners

func GetMaxListeners() int

GetMaxListeners returns the max listeners for this emmiter see SetMaxListeners

func Len

func Len() int

Len returns the length of all registered events

func ListenerCount

func ListenerCount(evt EventName) int

ListenerCount returns the length of all registered listeners to a particular event

func On

func On(evt EventName, listener ...Listener)

On registers a particular listener for an event, func receiver parameter(s) is/are optional

func Once

func Once(evt EventName, listener ...Listener)

Once adds a one time listener function for the event named eventName. The next time eventName is triggered, this listener is removed and then invoked.

func RemoveAllListeners

func RemoveAllListeners(evt EventName) bool

RemoveAllListeners removes all listeners, or those of the specified eventName. Note that it will remove the event itself. Returns an indicator if event and listeners were found before the remove.

func SetMaxListeners

func SetMaxListeners(n int)

SetMaxListeners obviously this function allows the MaxListeners to be decrease or increase. Set to zero for unlimited

Types

type EventEmmiter

type EventEmmiter interface {
	// AddListener is an alias for .On(eventName, listener).
	AddListener(EventName, ...Listener)
	// Emit fires a particular event,
	// Synchronously calls each of the listeners registered for the event named
	// eventName, in the order they were registered,
	// passing the supplied arguments to each.
	Emit(EventName, ...interface{})
	// EventNames returns an array listing the events for which the emitter has registered listeners.
	// The values in the array will be strings.
	EventNames() []EventName
	// GetMaxListeners returns the max listeners for this emmiter
	// see SetMaxListeners
	GetMaxListeners() int
	// ListenerCount returns the length of all registered listeners to a particular event
	ListenerCount(EventName) int
	// Listeners returns a copy of the array of listeners for the event named eventName.
	Listeners(EventName) []Listener
	// On registers a particular listener for an event, func receiver parameter(s) is/are optional
	On(EventName, ...Listener)
	// Once adds a one time listener function for the event named eventName.
	// The next time eventName is triggered, this listener is removed and then invoked.
	Once(EventName, ...Listener)
	// RemoveAllListeners removes all listeners, or those of the specified eventName.
	// Note that it will remove the event itself.
	// Returns an indicator if event and listeners were found before the remove.
	RemoveAllListeners(EventName) bool
	// RemoveListener removes given listener from the event named eventName.
	// Returns an indicator whether listener was removed
	RemoveListener(EventName, Listener) bool
	// Clear removes all events and all listeners, restores Events to an empty value
	Clear()
	// SetMaxListeners obviously this function allows the MaxListeners
	// to be decrease or increase. Set to zero for unlimited
	SetMaxListeners(int)
	// Len returns the length of all registered events
	Len() int
}

EventEmmiter is the message/or/event manager

func New

func New() EventEmmiter

New returns a new, empty, EventEmmiter

type EventName

type EventName string

EventName is just a type of string, it's the event name

func EventNames

func EventNames() []EventName

EventNames returns an array listing the events for which the emitter has registered listeners. The values in the array will be strings.

type Events

type Events map[EventName][]Listener

Events the type for registered listeners, it's just a map[string][]func(...interface{})

Example

// regiter our events to the default event emmiter
for evt, listeners := range testEvents {
	On(evt, listeners...)
}

user := "user1"
room := "room1"

createUser(user)
joinUserTo(user, room)
leaveFromRoom(user, room)

Output:

A new User just created!
A new User just created, *from second event listener
user1 joined to room: room1
user1 left from the room: room1

func (Events) CopyTo

func (e Events) CopyTo(emmiter EventEmmiter)

CopyTo copies the event listeners to an EventEmmiter

type Listener

type Listener func(...interface{})

Listener is the type of a Listener, it's a func which receives any,optional, arguments from the caller/emmiter

func Listeners

func Listeners(evt EventName) []Listener

Listeners returns a copy of the array of listeners for the event named eventName.