eventbus

An event bus in Common Lisp.

Getting Started in eventbus

Download and load

1 - Load eventbus system by quicklisp

(ql:quickload :eventbus)

2 - Download and Load eventbus system by github and asdf

Download directly from github:

git clone https://github.com/noloop/eventbus.git

and load by ASDF:

(asdf:load-system :eventbus)

Note: Remember to configure asdf to find your directory where you downloaded the libraries (asdf call them "systems") above, if you do not know how to make a read at: https://common-lisp.net/project/asdf/asdf/Configuring-ASDF-to-find-your-systems.html or https://lisp-lang.org/learn/writing-libraries.

Create eventbus instance

(let ((eventbus-instance (make-eventbus)))
  ;; ...
  )

Add listener in event once

An once event is an event that can only be emitted once because the added listener is deleted after it is first emitted.

(let ((eventbus-instance (make-eventbus)))
  (once eventbus-instance :my-event-name
        (lambda ()
          ;;do something
          )))

Add listener in event on

An on event is an event that can be emitted multiple times.

(let ((eventbus-instance (make-eventbus)))
  (on eventbus-instance :my-event-name
      (lambda ()
        ;;do something
        )))

You can also pass arguments to the listener function, both in once and on. See example:

(let ((eventbus-instance (make-eventbus)))
  (once eventbus-instance :my-event-name
        (lambda (arg1 arg2 arg3)
          ;;do something with arg1 arg2 arg3
          ))
  (on eventbus-instance :my-event-name
      (lambda (arg1 arg2 arg3)
        ;;do something with arg1 arg2 arg3
        )))

Remove listener of event

You can remove listeners that have been added, both in once and on.

(let ((eventbus-instance (make-eventbus))
      (listener-fn (lambda () t)))
  (on eventbus-instance :my-event-name listener-fn)
  (off eventbus-instance :my-event-name listener-fn))

Emit event

When emitting events, it is possible to pass arguments that will be passed to the listener function.

(let ((eventbus-instance (make-eventbus))
      (listener-fn (lambda (a b c) (format t "~a" (list a b c)))))
  (on eventbus-instance :my-event-name listener-fn)
  (emit eventbus-instance :my-event-name 1 2 3))
  
=> (1 2 3)

Get listener count of event

Return length listeners of event. Return nil if event nonexistent.

(let ((eventbus-instance (make-eventbus))
      (listener-fn (lambda () t)))
  (on eventbus-instance :my-event-name listener-fn)
  (get-listener-count-of-event eventbus-instance :my-event-name))

=> 1

Get all listeners from event

Return two values, the value: list of listeners of the event, and present-p: list is present.

(let ((eventbus-instance (make-eventbus))
      (listener-fn (lambda () t)))
  (on eventbus-instance :my-event-name listener-fn)
  (get-all-listeners-of-event eventbus-instance :my-event-name))

=> ((#<FUNCTION (LAMBDA ()) {10021B457B}> NIL))
T

Get all event names

Return one list with all name of events of the eventbus. The list returned includes add-listener and remove-listener.

(let ((eventbus-instance (make-eventbus))
      (listener-fn (lambda () t)))
  (on eventbus-instance :my-event-name1 listener-fn)
  (on eventbus-instance :my-event-name2 listener-fn)
  (get-all-events-name eventbus-instance))

=> (:MY-EVENT-NAME1 :MY-EVENT-NAME2)

Remove all listeners of event

Removing all listeners from the event. Will be called the off function for each listener, so the remove-listener event is emitted correctly for each listener removed.

(let ((eventbus-instance (make-eventbus))
      (listener-fn (lambda () t)))
  (once eventbus-instance :my-event-name listener-fn)
  (on eventbus-instance :my-event-name listener-fn)
  (on eventbus-instance :my-event-name listener-fn)
  (remove-all-listeners-of-event eventbus-instance :my-event-name))

=> NIL

Events :add-listener and :remove-listener

There are two standard eventbus events, :add-listener is emitted when a new listener is added to an event, while :remove-listener is emitted when a listener is removed from an event.

(let ((eventbus-instance (make-eventbus))
      (listener-fn (lambda () t)))
  (on eventbus-instance :add-listener
      (lambda ()
        ;; do something when emitted :add-listener event
        ))
  (on eventbus-instance :remove-listener
      (lambda ()
        ;; do something when emitted :remove-listener event
        ))
  (on eventbus-instance :my-event-name listener-fn)
  (off eventbus-instance :my-event-name listener-fn))

Chained functions

The on, once, off, emit and remove-all-listeners-of-event functions can be cahined, see an example:

(let ((eventbus-instance (make-eventbus))
      (listener-fn (lambda () (print 'HERE!))))
  (emit
   (on eventbus-instance :my-event-name listener-fn)
   :my-event-name))

=> HERE! 
#<HASH-TABLE :TEST EQ :COUNT 1 {1003F475A3}>

Above is returned hash-table, which is an instance of eventbus. Returning the instance of eventbus that causes the functions to be chained.

API

function (make-eventbus) => eventbus-instance

function (get-listener-count-of-event eventbus event-name) => count

function (get-all-listeners-of-event eventbus event-name) => list-of-listeners

function (once eventbus event-name listener-fn) => eventbus-instance

function (on eventbus event-name listener-fn) => eventbus-instance

function (off eventbus event-name listener-fn) => eventbus-instance

function (emit eventbus event-name &rest args) => eventbus-instance

function (get-all-events-name eventbus) => list-of-event-names

function (remove-all-listeners-of-event eventbus event-name) => eventbus-instance

event :add-listener

event :remove-listener