com.apama.correlator.jms
Event JMSReceiverFlowControlMarker
A control event periodically sent to an EPL application for each receiver with receiverFlowControl enabled, which the application uses to update the flow control window.
This event is used as a baseline from which the EPL application specifies the size of the window of new events it is currently ready to receive, specified relative to the last event received before this marker.
The event is sent: i) when a receiver with receiverFlowControl=true is first added (once onApplicationInitialized has been called), ii) during recovery (in a persistent correlator), and iii) also periodically as JMS messages are received and sent to the correlator (typically these events are sent as often as the configured maxBatchSize, e.g. at least once every 1000 events).
To correctly implement the receiver flow control protocol, applications must respond to this event by calling updateFlowControlWindow (see below) to indicate the maximum number of additional events that the JMS runtime should take from this receiver, using the point in the event stream at which this marker was received as the baseline.
Applications that wish to use flow control to throttle message receiving based on the number of outstanding asynchronous operations from already-received messages (to put a finite bound on memory usage) should also cache the most recent JMSReceiverFlowControlMarker for each active JMSReceiver so that the flow control window can be updated (e.g. extended) as pending operations complete, since there is no guarantee another JMSReceiverFlowControlMarker event will be sent until the window is extended enough for more events to be received.
Note that the fields of this event (apart from receiverId) are intended as 'opaque' data for internal use only and should be ignored by customer code.
-
See Also:
-
com.apama.correlator.jms.JMSReceiverFlowControlMarker#updateFlowControlWindow() - Set the flow control window for this receiver, relative to this marker.
| Action summary |
void | updateFlowControlWindow(integer windowSizeEvents)
Sets the current flow control window size for a given receiver, which indicates the number of extra Apama events that should be taken from JMS and passed to the application before blocking, relative to the last data event received before this marker. |
__flowControlMarker
integer __flowControlMarker
For internal use only, treat as opaque data.
__processInstanceToken
integer __processInstanceToken
For internal use only, treat as opaque data.
receiverId
string receiverId
The unique identifier of this receiver.
updateFlowControlWindow
void updateFlowControlWindow(integer windowSizeEvents)
Sets the current flow control window size for a given receiver, which indicates the number of extra Apama events that should be taken from JMS and passed to the application before blocking, relative to the last data event received before this marker.
-
Parameters:
-
windowSizeEvents - The maximum number of new events that should be received from this JMS receiver and sent to the correlator, relative to the position in the event flow indicated by this marker. The window size may be a constant number (e.g. 10,000 events) for applications that immediately process received events to completion, or it may have a number of 'pending' events subtracted from it to create a bound on on the number of events that may be received from the JMS broker but are not yet been fully processed by the application (e.g. if an asynchronous database operation must complete before the memory, data structures or event listeners associated with the event may be deleted).
It is valid to supply a zero or negative number for this value, in which case the JMS runtime will attempt to pause receiving, and take no more messages from the JMS queue/topic until this action is called again with a positive window (though it is not possible to guarantee that the flow of events will stop immediately, since some events could already be queued up). To allow an unbounded number of events to be received, specify integer.MAX for windowSizeEvents.
It is important that the overall long-term maximum window size (i.e. the chosen constant upper bound, ignoring any currently pending operations) is greater than than the receiver's maxBatchSize (typically 1000).