Monitor lifecycle
Monitors are compiled and run (executed) by the Apama correlator. The correlator starts executing in the monitor's onload() action. To execute a monitor, you load (inject) it into the correlator. The correlator then does the following:
1. Compiles the monitor's source text
2. If no errors are detected, creates the main monitor instance along with its global variables
3. Invokes the monitor instance's onload() action
When the onload() action has executed to completion (that is, the control path reaches the closing curly brace of the onload() action), if the monitor instance has event listeners or streaming networks, then it remains active but in a suspended state.
The correlator calls the monitor instance's event listeners whenever it detects events that match the event listeners' event expressions.
A monitor instance terminates when one of the following events occurs:
The monitor instance executes a
die statement in one of its actions.
A runtime error condition is raised.
The monitor is terminated externally (for example, with the
engine_delete utility.
The monitor instance has executed all its code and there are no remaining listeners or streaming networks. This will occur rapidly if the
onload() action does not create any.
When a monitor instance terminates, the correlator does the following:
1. Invokes the monitor instance's ondie() action, if it is defined.
2. If the monitor instance that is terminating is the last active instance of that monitor, the correlator also does the following:
Invokes the monitor's
onunload() action if it is defined.
Removes the monitor's code from the correlator.
Frees all the monitor's resources.
To summarize, consider that when a monitor spawns monitor instances, there is a set of monitors that includes the original monitor instance and any spawned monitor instances. As the monitor instances in this set terminate, the correlator calls the ondie() action, if it is defined, for each monitor instance that terminates. When the last monitor instance in the set terminates, the correlator also calls the onunload() action. Thus, the correlator calls ondie() once for each monitor instance in the set, and calls onunload() only once for the entire set.
See
About executing ondie() actions for information about how
ondie() can optionally receive exception information if an instance dies due to an uncaught exception.