Asynchronous plug-ins
It is possible to write a plug-in that can send events asynchronously to the correlator. This is not a recommended technique as multiple correlator processes or external processes connected via the client API are preferred approaches to scaling Apama deployments. However, an example of how to implement asynchronous plug-ins is available in the samples\correlator_plugin\cpp directory of the Apama installation, and is called async_plugin.cpp.
This is a simple example which uses the getCorrelator() method of AP_Context to get a reference to an AP_CorrelatorInterface.
The single public method of AP_CorrelatorInterface is declared as follows:
/**
* Send an event to the correlator
*
* @param event the event to send. The event is represented as a string
* using the format described in Deploying and Managing Apama Apps.
* See the correlator utilities section, Event File Format.
*/
virtual void sendEvent(const char* event) const = 0;
The correlator implements this method by using the same event queuing and asynchronous processing mechanism as is used for the EPL enqueue keyword.
In this sample, the plug-in has one function exposed that is also called sendEvent. This function demonstrates the feature by simply sending the data it was given back to the correlator. A more elaborate use of this mechanism might use its own background processing thread to occasionally send events to the correlator.
Examples of using the sendEvent method include:
ctx.getCorrelator()->sendEvent("SimpleCounter(1)");
This will dispatch the event of type SimpleCounter with a single integer field set to 1.
Also, in the sample discussed above it is used thus:
ctx.getCorrelator()->sendEvent(args[0].stringValue());
Here the event provided by the first argument is the complete event to be dispatched.
There is one area where extra caution is required when building asynchronous plug-ins, which is the lifetime of variables within the plug-in. When a plug-in function is called with an AP_Context argument, that context is valid only for the duration of the call (and only on that thread). However, the AP_CorrelatorInterface remains valid for the lifetime of the plug-in. References to it may be retained and used at any time on any thread. This information is important to anyone writing a plug-in that may be holding references to an AP_CorrelatorInterface, for example, in another thread. The plug-in author must ensure that when the plug-in is shutdown these references are cleaned up, since attempts to use these references after the plug-in has been shutdown may cause instability of the correlator.