bell

README

Bell

Bell is the simplest event system written in Go (Golang) which is based on the execution of handlers independent of the main channel.

• Written in pure go. Has no third-party libraries.
• Support for custom event data.
• Internally, it launches each handler in a separate goroutine and passes messages to them through channels, the handlers are executed independently of the main thread.
• Support for adding multiple handlers to an event.
• Complete unit testing.

Installation

To install Bell package, you need install Go with modules support and set Go workspace first.

1. Use the below Go command to install Bell:

go get -u github.com/nuttech/bell

1. Import package in your code:

import "github.com/nuttech/bell"

Usage

Adding event listener

The handler function accepts the Message structure as input

bell.Listen("event_name", func(message bell.Message) {
	// here you must write your handler code
})

Struct Message (bell.Message)

type Message struct {
	Event     string // event name
	Timestamp time.Time // time when the event was called
	Value     interface{} // any data
}

You can add more handlers one event:

bell.Listen("event_name", func(message bell.Message) { 
	// first handler
})
bell.Listen("event_name", func(message bell.Message) {
	// second handler
})

Calling an event

This code call event. Activating handlers, who subscribed on "event_name" event

bell.Call("event_name", "some data")

bell.Call("event_name", 1) // int

bell.Call("event_name", false) // bool

If you passing struct type of data:

type userStruct struct {
	Name string
}
bell.Call("event_name", userStruct{Name: "Jon"})

Then parsing the data in the handler may look like this:

bell.Listen("event_name", func(message bell.Message) {
	user := message.Value.(userStruct)
	
	fmt.Printf("%#v\n", userStruct{Name: "Jon"})  // main.userStruct{Name:"Jon"}
})

Getting events list

To get a list of events to which handlers are subscribed, call the code:

bell.List()

Checking if exists listeners of event

You can check the existence of subscribers to an event like this:

bell.Has("event_name")

Removing listeners of event (all events)

You can delete all listeners or listeners of only one event.

Removing all listeners on all events

_ = bell.Remove()

Removing listeners of only the event "event_name"

_ = bell.Remove("event_name")

Examples

See full example in example_test.go.

Documentation

Overview

Package bell implements a simple event system (bell ringing and listening)

Several listeners can be added for each ringing (handlerFunc). Listeners are called in a separate goroutine through an established channel. When the bell rings, a message is sequentially transmitted to each listener.

If a channel is closed, the goroutine for that event is terminated.

Example for usage: Listen("event_name", func(message Message) { fmt.PrintLn(message) }) - add listener on bell by name "event_name" Ring("event_name", "some_data") - Ring on bell (call event "event_name")

Example

package main

import (
	"fmt"
	"github.com/nuttech/bell"
	"sort"
	"time"
)

type CustomStruct struct {
	name  string
	param int32
}

func main() {
	event := "event_name"
	event2 := "event_name_2"

	// add listener on event event_name
	bell.Listen(event, func(message bell.Message) {
		// we extend CustomStruct in message.Value
		customStruct := message.Value.(CustomStruct)
		fmt.Println(customStruct)
	})
	// add listener on event event_name_2
	bell.Listen(event2, func(message bell.Message) {

	})

	// get event list
	list := bell.List()

	// only for test
	sort.Strings(list)
	fmt.Println(list)

	// remove listeners on event_name_2
	bell.Remove(event2)

	// get event list again
	fmt.Println(bell.List())

	// check if exists event_name_2 event in storage
	fmt.Println(bell.Has(event2))

	// call event event_name
	_ = bell.Ring(event, CustomStruct{name: "testName", param: 12})

	// ONLY FOR EXAMPLE
	// add sleep because the event handler does not have time
	// to be processed before the completion of the script execution
	time.Sleep(time.Millisecond * 50)

}

Output:

[event_name event_name_2]
[event_name]
false
{testName 12}

Index

• func Has(event string) bool
• func List() []string
• func Listen(event string, handlerFunc func(message Message))
• func Remove(names ...string)
• func Ring(event string, value interface{}) error
• type Message

Examples

• Package

Functions

func Has

func Has(event string) bool

Has Checks if there are listeners for the passed event

func List

func List() []string

List Returns a list of events that listeners are subscribed to

func Listen

func Listen(event string, handlerFunc func(message Message))

Listen Subscribe on event where event - the event name, handlerFunc - handler function

func Remove

func Remove(names ...string)

Remove Removes listeners by event name Removing listeners closes channels and stops the goroutine.

If you call the function without the "names" parameter, all listeners of all events will be removed.

func Ring

func Ring(event string, value interface{}) error

Ring Call event there event - event name value - data that will be passed to the event handler

Types

type Message

type Message struct {
	Event     string
	Timestamp time.Time
	Value     interface{}
}

Message The message that is passed to the event handler