event.q

Event Manager

This library provides a method of executing one or more functions when specific "event" occur. This follows the observer pattern with functions acting as "listeners" to "events" that occur within the kdb process.

Events can be attached to specific kdb handlers (e.g. .z.po) or can be fired manually when application specific events occur.

Note that this library uses the .log.debug|info|warn log functions. For improved log information and to suppress debug logging from the console, you can use the log library.

Core Handlers

When the event library is loaded, it attaches itself to a number of kdb handlers and provides friendly event names for them:

• .z.po
  • Event name: port.open
• .z.pc
  • Event name: port.close
• .z.exit
  • Event name: process.exit

This list can be extended by adding entries to the .event.cfg.coreHandlers dictionary prior to initialisation of the library.

As part of the initialisation, the event library will install a default process exit handler to log to the console when the process exits. This can be configured by changing the .event.cfg.addDefaultExitHandler boolean.

Default Exit Handler

q)exit 0
Notifying listeners of event [ Event: process.exit ] [ Args: 0i ]
Process is exiting at 2017.03.29D14:20:45.988310000 [ Exit Code: 0 ]

C:\Users\jasra_000\git\kdb-common>

Adding a Listener

A listener is a function that will execute when an event occurs. Multiple listeners can be attached to the same event allowing for isolation of code that is independent but rely on the the same event to execute.

When an event is fired, it can pass arguments to the listeners to provide context around the event fired. It is important that the listener can accept the correct number of arguments.

Listeners are added with .event.addListener. This function will validate that the function exists prior to adding it to the event list. The function will silently disallow any attempt to the same listener to the same event multiple times.

Example

q) .notify.func:{ -1 "Notified with arg: ",string x }
q) .event.addListener[`my.event; `.notify.func]
New event type to be added for management [ Event: my.event ]
New listener added for event [ Event: my.event ] [ Listener: .notify.func ]

Firing an Event

To fire an event and notify all listeners, use .event.fire. You can fire events that have no listeners will no side effects. If a listener fails to execute it will be logged to the console (with .log.warn) with all listeners and the exceptions thrown logged.

Firing with Listeners

q) .event.fire[`my.event; 12345]
Notifying listeners of event [ Event: my.event ] [ Args: 12345 ]
Notified with arg: 12345

Firing with No Listeners

q) .event.fire[`no.listeners; 12345]
Event fired but no listeners [ Event: no.listeners ] [ Args: 12345 ]

Firing with Listener Error

q) .notify.error:{ 1+`a }
q) .event.addListener[`my.event; `.notify.error];
New listener added for event [ Event: my.event ] [ Listener: .notify.error ]

q) .event.fire[`my.event; 12345]
Notifying listeners of event [ Event: my.event ] [ Args: 12345 ]
Notified with arg: 12345
One or more listeners failed to execute successfully [ Event: my.event ] [ Errored: ,`.notify.error ]
Listener exception detail:
.notify.error| "type"

Listener Configuration

The event and listener configuration is defined in .event.handlers. The default configuration post initialisation is as follows:

q).event.handlers
port.open   | `symbol$()
port.close  | `symbol$()
process.exit| ,`.event.i.defaultExitHandler

Removing Listener

A listener can be removed from listening to an event by using the .event.removeListener function.