Using callbacks and custom events

Using Callbacks and Custom Events

Version 2.0

Callbacks: What and Why

Callbacks and custom events were introduced in v2.0 to give built-in API components and the applications built with them access to daemon state transitions with some level of decoupling.

Events

All built-in events are aliased as class constants in the Core_Daemon class.

• Core_Daemon::ON_ERROR

  Dispatched when the log() method is called with an $is_error=true argument. The message passed to log() is passed through to the event. See the logging documentation for more details.

• Core_Daemon::ON_SIGNAL

  Dispatched every time your daemon application receives a signal. This can be used in your application to create custom signal handlers. The signal (int) is passed as an argument.

• Core_Daemon::ON_INIT

  The static getInstance constructor starts daemon applications in INIT state. Callbacks you register to the state will be called immediately after plugins and workers are setup, before your daemon setup() method is called.

• Core_Daemon::ON_RUN

  The ON_RUN callbacks are dispatched each time the daemon's main event loop iterates. This event is dispatched after system-level tasks are taken care of, and before your execute() method is called. You can use it to create new system-level services that run transparently to your application, split-up work that would normally be incongruously lumped together in the execute() method into their own objects and methods that register themselves and run in beautifully decoupled bliss.

• Core_Daemon::ON_FORK

  Dispatched before any processes are forked -- which could mean either that you've called fork() explicitly in your application to run a simple ad hoc background task, or that you're using the Workers api for parallel processing. Note, though: The workers API may fork unpredictably. It selects a forking strategy based on runtime variables, ranging from pre-forking a max number of worker processes to forking one at a time, on-demand as needed.

• Core_Daemon::ON_PIDCHANGE

  After processes are forked the system will dispatch an event to inform listeners that the PID has changed. This is important to you if you're caching the pid in a variable the way we do in lock plugins and the Core_Daemon class itself.

• Core_Daemon::ON_SHUTDOWN

  The ON_SHUTDOWN event is dispatched as the daemon begins its shutdown process -- before any plugin or worker teardown() methods are called.

Callbacks

You can add callbacks to these events very easily using the on() method. The first argument is the event, the second is a closure or callback.

The on() method returns a callback tuple that can be used later to turn off the callback using the off() method.

Custom Events

Creating custom events is very simple.

1. Add a class-constant using the same style as built-in event constants using numeric values > 100 to prevent conflict with any future built-in events.
2. In your code at the event point, call the dispatch() method. The first argument informs the event that is being dispatched, the second is an optional array of arguments to be passed with the event.

The first argument can either be an array with a single element -- the event constant, or it can be the 2-element array that was returned when you registered a callback using on(). In other words, you can pass that return tuple to dispatch() to call a function you've previously registered. While this is admittedly slightly obtuse and without wide use cases, it does give you the ability to dispatch an event handler by ID only without concern to the implementation of the underlying function.

Dispatching a Fork event in Core_Daemon:

$this->dispatch(array(self::ON_FORK));