Chapter 9 Working With Rules and Functions : Working With Event Preprocessors

Working With Event Preprocessors
Event preprocessors are rule functions with one argument of type simple event. They perform tasks after an incoming message is transformed into a simple event but before it is asserted into working memory.
You can modify and enrich events before they are asserted into working memory. Rule evaluation depends on event values at time of assertion, so they can be changed only before assertion.
Modifying concepts not permitted  A preprocessor can assert and delete concepts, but cannot modify concepts (doing so could disrupt an RTC).
Locking  If you are using multi-engine (engine concurrency) features, you must use locking as appropriate to coordinate access to objects. See Locking and Synchronization Functions in Preprocessors.
Reminder, Cache Only cache mode  If you are using the Cache Only cache mode (advanced option) for one or more entities, you must consider how to handle any cache-only entities used in the functions. See Explicitly Loading Objects into Working Memory, With the Cache Only Mode.
How Configured
To configure a preprocessor you associate the desired rule function with a destination in the Input Destinations tab of the BusinessEvents Archive resource (see Configuring a BAR File for Deployment):
Worker Threading and Queue Options
Event preprocessing is multi-threaded for high performance. When you configure a preprocessor you also define thread settings. This section explains the advantages of each option, specifically considering JMS destinations. Each JMS Destination creates a separate JMS Session internally, and creates a JMS thread and a dedicated JMS Connection for itself.
Caller’s Thread
Uses the thread (and queue size) provided by the channel resource client (the Rendezvous or Enterprise Message Service client, for example).
Advantages
Less context switching  The messaging library's thread does the message delivery, pre-processing and the Rete operations.
Self-throttling  The messaging system cannot push events faster than the rate at which it can get consumed.
Disadvantages
Because each destination creates a JMS session, a session might be under used. On some operating systems, sockets and sessions could be very under-used.
Shared Queue and Threads
Uses the BusinessEvents system-wide shared queue and threads. (In this case there is no dedicated queue for each destination.) See Shared Queue and Threads Properties for related property settings.
Advantages
Good for Multi-core machines  which can make good use of a heavily threaded set-up.
Disadvantages
Use of multiple queues makes it hard to match inbound and outbound (or RTC) rates. It can be harder to tune performance.
Dedicated Workers Option (Specified Number of Threads)
Specifies a number of threads. BusinessEvents creates this number of new worker threads for the input destination. (In this case there is a dedicated queue for each destination). When you choose this option, you must also specify the Queue Size.
This option is similar to the Shared Queue option except that the Destination has a dedicated thread pool and set of worker threads to process messages.
The advantages and disadvantages are similar to those for Shared Queue and Threads.
Locking and Synchronization Functions in Preprocessors
Because the event preprocessor is multi-threaded, multiple preprocessor threads must coordinate access to objects through appropriate use of locking. To achieve locking, use the provided synchronization functions. These functions have a format similar to the Java synchronized keyword:
Coherence.C_Lock(String key, long timeout, boolean LocalOnly)
If you want to acquire the lock only within the agent, set LocalOnly to true. Set the LocalOnly parameter to false to acquire the lock cluster wide.
The thread that calls the C_Lock() function is the only thread that gets blocked, until the thread that was holding the lock earlier releases.
Note that it is advisable (but not necessary) to use the corresponding C_Unlock() function. All the locks acquired during event processing are released at the end of the RTC cycle, that is, after data is written to cache.
The format of the unlock function is as follows:
Coherence.C_UnLock(String key, boolean LocalOnly)
The Coherence.C_Lock() and Coherence.C_UnLock() functions are available only in event preprocessors.
The example LockExample (in BE_HOME/examples) demonstrates these points, showing use of locks to prevent race conditions.
Example
Suppose an event preprocessor is associated with a JMS destination. The preprocessor function uses locking and unlocking. Here is what BusinessEvents does:
1.
2.
3.
4.
a.
b.
5.