When the behavior of a C++ plug-in is that it never blocks or does not usually block you can declare the plug-in to be nonblocking. Even if one or more methods defined in a plug-in might block, you can declare the plug-in to be nonblocking and override the nonblocking designation for just the methods that might block. The benefit of declaring a plug-in to be nonblocking is that the correlator refrains from creating unneeded processing threads.

By default, the correlator assumes that any plug-in method or handler it calls might block for an arbitrary amount of time. Consequently, the correlator creates additional threads to continue processing other contexts. If the plug-in method/handler does not block, these extra threads represent an expense that could be avoided.

To declare a plug-in as nonblocking, define an AP_PLUGIN_GET_CAPABILITIES_FUNCTION_NAME function that returns AP_CAPABILITIES_NON_BLOCKING. See the AP_PluginCommon.h header file in the include directory of your Apama installation directory for the definition of AP_PLUGIN_GET_CAPABILITIES_FUNCTION_NAME. The correlator calls this function before it calls the plug-in’s init() function. The return value is an AP_Capabilities object that contains a bit-wise OR of capabilities, as defined in the AP_PluginCommon.h header file.

When you declare a plug-in to be nonblocking the correlator lets plug-in methods and any plug-in event handlers process to completion without spawning new threads.

You must ensure that a plug-in declared to be nonblocking does not block. If a nonblocking plug-in does block it can cause a correlator deadlock. To avoid this, for each plug-in method that might block, be sure to override the nonblocking designation. For example, consider a method that accesses a local cache. Normally, this method would not block. However, if the method uses a remote process when the needed object is not in the local cache then the method might block. You must override the nonblocking designation for a method such as this one.

A plug-in that you declare as nonblocking can have one or more methods that might block. In each method that might block, you must call the pluginMethodBlocking() function on either an AP_Context object or an AP_CorrelatorInterface object. The signature for the pluginMethodBlocking() function is as follows for each type of object:

Calling pluginMethodBlocking() is idempotent. A call to pluginMethodBlocking() informs the correlator that the containing method might block and that the correlator should start additional threads to compensate.