The eventbus Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The eventbus Reference Manual

This is the eventbus Reference Manual, version 0.1.0, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Apr 08 13:59:36 2019 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

eventbus

An event bus in Common Lisp.

Getting Started in eventbus

Download and installation

1 - Download eventbus system

By quicklisp:

IN PROGRESS...

or directly from github:

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

2 - Install eventbus

By quicklisp:

IN PROGRESS...

or directly from 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 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)))
  (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


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 eventbus

Maintainer

noloop <noloop@zoho.com>

Author

noloop <noloop@zoho.com>

Home Page

https://github.com/noloop/eventbus

Source Control

(:git "git@github.com:noloop/eventbus.git")

Bug Tracker

https://github.com/noloop/eventbus/issues

License

GPLv3

Description

An event bus in Common Lisp.

Version

0.1.0

Source

eventbus.asd (file)

Component

src (module)


Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.


Previous: , Up: Modules   [Contents][Index]

3.1 eventbus/src

Parent

eventbus (system)

Location

src/

Components

Next: , Previous: , Up: Top   [Contents][Index]

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 eventbus.asd

Location

eventbus.asd

Systems

eventbus (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 eventbus/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

noloop.eventbus


Previous: , Up: Lisp files   [Contents][Index]

4.1.3 eventbus/src/eventbus.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/eventbus.lisp

Exported Definitions
Internal Definitions

make-listener (function)


Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

5.1 noloop.eventbus

Source

package.lisp (file)

Nickname

eventbus

Use List

common-lisp

Exported Definitions
Internal Definitions

make-listener (function)


Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Functions

Function: emit EVENTBUS EVENT-NAME &rest ARGS

Emite an event by passing the arguments offered to the listener function. If the listener is once, then the listener is excluded from the list of listeners.

Package

noloop.eventbus

Source

eventbus.lisp (file)

Function: get-all-events-name EVENTBUS

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

Package

noloop.eventbus

Source

eventbus.lisp (file)

Function: get-all-listeners-of-event EVENTBUS EVENT-NAME

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

Package

noloop.eventbus

Source

eventbus.lisp (file)

Function: get-listener-count-of-event EVENTBUS EVENT-NAME

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

Package

noloop.eventbus

Source

eventbus.lisp (file)

Function: make-eventbus ()

Return eventbus instance.

Package

noloop.eventbus

Source

eventbus.lisp (file)

Function: off EVENTBUS EVENT-NAME LISTENER-FN

Remove the first listener from the event listeners list.

Package

noloop.eventbus

Source

eventbus.lisp (file)

Function: on EVENTBUS EVENT-NAME LISTENER-FN

Add one listener to an event. The add-listener event is emitted before adding the new listener.

Package

noloop.eventbus

Source

eventbus.lisp (file)

Function: once EVENTBUS EVENT-NAME LISTENER-FN

Add one listener to an event. The listener is removed when the event is emitted. The add-listener event is emitted before adding the new listener.

Package

noloop.eventbus

Source

eventbus.lisp (file)

Function: remove-all-listeners-of-event EVENTBUS EVENT-NAME

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.

Package

noloop.eventbus

Source

eventbus.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Functions

Function: make-listener LISTENER-FN IS-ONCE

It returns a list, the first element being a listener function, and the following being a boolean saying if it is an once listener.

Package

noloop.eventbus

Source

eventbus.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   E   F   L   M  
Index Entry  Section

E
eventbus.asd: The eventbus<dot>asd file
eventbus/src: The eventbus/src module
eventbus/src/eventbus.lisp: The eventbus/src/eventbus<dot>lisp file
eventbus/src/package.lisp: The eventbus/src/package<dot>lisp file

F
File, Lisp, eventbus.asd: The eventbus<dot>asd file
File, Lisp, eventbus/src/eventbus.lisp: The eventbus/src/eventbus<dot>lisp file
File, Lisp, eventbus/src/package.lisp: The eventbus/src/package<dot>lisp file

L
Lisp File, eventbus.asd: The eventbus<dot>asd file
Lisp File, eventbus/src/eventbus.lisp: The eventbus/src/eventbus<dot>lisp file
Lisp File, eventbus/src/package.lisp: The eventbus/src/package<dot>lisp file

M
Module, eventbus/src: The eventbus/src module

Jump to:   E   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   E   F   G   M   O   R  
Index Entry  Section

E
emit: Exported functions

F
Function, emit: Exported functions
Function, get-all-events-name: Exported functions
Function, get-all-listeners-of-event: Exported functions
Function, get-listener-count-of-event: Exported functions
Function, make-eventbus: Exported functions
Function, make-listener: Internal functions
Function, off: Exported functions
Function, on: Exported functions
Function, once: Exported functions
Function, remove-all-listeners-of-event: Exported functions

G
get-all-events-name: Exported functions
get-all-listeners-of-event: Exported functions
get-listener-count-of-event: Exported functions

M
make-eventbus: Exported functions
make-listener: Internal functions

O
off: Exported functions
on: Exported functions
once: Exported functions

R
remove-all-listeners-of-event: Exported functions

Jump to:   E   F   G   M   O   R  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables


Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   E   N   P   S  
Index Entry  Section

E
eventbus: The eventbus system

N
noloop.eventbus: The noloop<dot>eventbus package

P
Package, noloop.eventbus: The noloop<dot>eventbus package

S
System, eventbus: The eventbus system

Jump to:   E   N   P   S