public interface EventQueue
An event queue object is a FIFO queue for message and timer events. Programs can add subscribers to a queue; remove subscribers from a queue; create and destroy timers on a queue; dispatch events from a queue; and stop a queue in preparation to destroy it.
To create an event queue object, call Realm.createEventQueue
.
Customers do not implement this interface.
Modifier and Type | Field and Description |
---|---|
static int |
DISCARD_NEW
Discard new events, instead of adding them to the queue.
|
static int |
DISCARD_NONE
Do not discard events (default behavior).
|
static int |
DISCARD_OLD
Discard old events from the head of the queue.
|
static java.lang.String |
PROPERTY_BOOL_INLINE_MODE
Inline mode (low-latency); boolean.
|
static java.lang.String |
PROPERTY_INT_DISCARD_POLICY
Discard policy; integer.
|
static java.lang.String |
PROPERTY_INT_DISCARD_POLICY_DISCARD_AMOUNT
Discard amount; integer.
|
static java.lang.String |
PROPERTY_INT_DISCARD_POLICY_MAX_EVENTS
Max events; integer.
|
static java.lang.String |
PROPERTY_STRING_NAME
Queue name; string.
|
Modifier and Type | Method and Description |
---|---|
void |
addDestSubscriber(DestSubscriber sub,
SubscriberListener listen)
Add a destination subscriber to the event queue
|
void |
addSubscriber(Subscriber sub,
SubscriberListener listen)
Add a subscriber to a queue.
|
long |
count()
Get the number of events in the queue.
|
EventTimer |
createTimer(double interval,
EventTimerListener listen)
Create and start a timer.
|
void |
destroy()
Destroy an event queue.
|
void |
destroyTimer(EventTimer timer)
Stop and destroy a timer.
|
void |
dispatch()
Dispatch message events; wait indefinitely for an event.
|
void |
dispatch(double seconds)
Dispatch message events; wait until timeout (in seconds) for
an event.
|
void |
dispatch(long timeout,
java.util.concurrent.TimeUnit units)
Dispatch message events; wait until timeout for an event.
|
void |
dispatchNow()
Dispatch message events; do not wait.
|
java.lang.String |
name()
Return the name of the event queue object.
|
void |
removeDestSubscriber(DestSubscriber sub)
Remove a destination subscriber from the event queue
|
void |
removeSubscriber(Subscriber sub)
Remove a subscriber from a queue.
|
static final java.lang.String PROPERTY_BOOL_INLINE_MODE
Programs that receive time-sensitive messages can use inline
mode to favor low latency over high throughput. Inline mode
reduces inbound message latency using inline transport I/O in
the same thread as the SubscriberListener
callback method.
Inline mode requires that callback methods always return quickly; otherwise, long callbacks can delay message I/O (defeating the purpose of inline mode).
Inline mode could reduce the average number of messages in the vectors that the callback receives.
It is good practice to dispatch an inline queue from only one thread. Dispatching an inline-mode queue from several threads could result in actual wait times that are longer than the dispatch timeout arguments. For example, if thread A dispatches with timeout 10 seconds, and thread B dispatches with timeout 15 seconds, then the timer for thread B does not start until after the dispatch call returns in thread A. The apparent timeout for thread B could be as long as 25 seconds.
When specifying inline mode, programmers must coordinate with administrators to avoid illegal state exceptions.
To enable inline mode, pass this property to
Realm.createEventQueue
with value true.
Otherwise, the default behavior disables inline mode.
static final java.lang.String PROPERTY_INT_DISCARD_POLICY
This property determines the behavior of the queue on overflow (too many events).
To enable discard on overflow, pass this property to
Realm.createEventQueue
.
Otherwise, the default behavior disables discard.
These members are the legal property values:
static final java.lang.String PROPERTY_INT_DISCARD_POLICY_MAX_EVENTS
When distributing an event to the queue would overflow this limit, the queue discards events.
If you specify a discard policy that could actually discard events, then you must also specify a value for this maximum.
static final java.lang.String PROPERTY_INT_DISCARD_POLICY_DISCARD_AMOUNT
When a queue overflows, this property determines the number of events to discard.
If you specify DISCARD_OLD
, you may also
specify this value. The value must be less than
PROPERTY_INT_DISCARD_POLICY_MAX_EVENTS
.
When absent, the default value is 1.
If you specify DISCARD_NEW
, then
Realm.createEventQueue
ignores this value.
Discarding new events always discards exactly enough events
so that the rest fit on the queue.
static final java.lang.String PROPERTY_STRING_NAME
It is good practice to assign a unique name to each event queue (that is, unique within the program). If the queue discards events, the advisory message identifies the queue using this name, which can help diagnose the issue.
static final int DISCARD_NONE
PROPERTY_INT_DISCARD_POLICY
,
Constant Field Valuesstatic final int DISCARD_OLD
PROPERTY_INT_DISCARD_POLICY
,
Constant Field Valuesstatic final int DISCARD_NEW
PROPERTY_INT_DISCARD_POLICY
,
Constant Field Valuesvoid addSubscriber(Subscriber sub, SubscriberListener listen) throws FTLException
Adding a subscriber to a queue associates the two objects, which
yields the following behavior: Each time the subscriber receives a
message, it distributes an event to the queue. The event includes
the inbound message and SubscriberListener
instance.
You can add a subscriber to at most one queue. If you have already added a subscriber to a queue, and you attempt to add it to another queue, this call throws an exception.
If you add several subscribers to the same queue, the queue merges their message streams.
sub
- The call adds this subscriber to the queue.listen
- Dispatching a message event invokes the callback method of this listener.FTLException
void removeSubscriber(Subscriber sub) throws FTLException
Removing a subscriber from a queue dissociates the two objects. The subscriber no longer distributes message events to the queue. Message events that the subscriber has already distributed to the queue remain in the queue.
Best practice is to remove all subscribers before destroying the event queue.
Associations between subscribers and queues are independent of one another; that is, removing one subscriber from a queue does not affect the association of other subscribers with that queue.
sub
- The call removes this subscriber from the queue.FTLException
EventTimer createTimer(double interval, EventTimerListener listen) throws FTLException
This call creates a timer object associated with the queue. The timer places a timer event on the queue at every interval (in seconds).
The interval repeats indefinitely; to stop it, the program must explicitly destroy the timer object.
Each time dispatch()
dispatches a timer event,
the EventTimerListener
callback processes the event.
interval
- The timer places events on the queue at this repeating interval (in seconds).listen
- Dispatching a timer event invokes the callback method of this listener.FTLException
void destroyTimer(EventTimer timer) throws FTLException
This call stops a timer so it does not place additional timer events on the queue. It also attempts to remove from the queue any timer events (associated with the stopped timer) that have fired but are not yet processed.
timer
- The call stops this timer.FTLException
void dispatch() throws FTLException
If the queue is not empty, this call scans events from the head of the queue to obtain a sequence of events that all contain the same listener. Scanning produces a list of messages, which the dispatch call passes to the listener for processing.
If the queue is empty, the call waits indefinitely for events to arrive.
FTLException
void dispatch(long timeout, java.util.concurrent.TimeUnit units) throws FTLException
If the queue is not empty, this call scans events from the head of the queue to obtain a sequence of events that all contain the same listener. Scanning produces a list of messages, which the dispatch call passes to the listener for processing.
If the queue is empty, the call waits for events to arrive. The timeout parameter determines the maximum time it can wait. Note that this parameter does not guarantee a minimum wait time.
If the timeout elapses before an event arrives in the queue, then the dispatch call returns normally. The call does not indicate whether or not it actually dispatched an event.
The call converts the timeout argument from the specified units to nanoseconds, then back to seconds, then passes the result to its underlying implementation framework.
timeout
- If the queue is empty, the call waits for an
event. If an event does not arrive before this
timeout elapses, the call returns.units
- The program specifies the timeout in these units.FTLException
void dispatch(double seconds) throws FTLException
If the queue is not empty, this call scans events from the head of the queue to obtain a sequence of events that all contain the same listener. Scanning produces a list of messages, which the dispatch call passes to the listener for processing.
If the queue is empty, the call waits for events to arrive. The timeout parameter determines the maximum time it can wait. Note that this parameter does not guarantee a minimum wait time.
If the timeout elapses before an event arrives in the queue, then the dispatch call returns normally. The call does not indicate whether or not it actually dispatched an event.
seconds
- If the queue is empty, the call waits for an
event. If an event does not arrive before this
timeout (in seconds) elapses, the call returns.FTLException
void dispatchNow() throws FTLException
If the queue is not empty, this call scans events from the head of the queue to obtain a sequence of events that all contain the same listener. Scanning produces a list of messages, which the dispatch call passes to the listener for processing.
If the queue is empty, this call returns immediately.
FTLException
void destroy() throws FTLException
Destroying a queue object frees all the resources associated with the queue. (However, this call does not implicitly close subscribers associated with the queue.)
Best practice is to remove all subscribers before destroying the event queue.
FTLException
long count() throws FTLException
The count includes both message events and timer events.
FTLException
java.lang.String name()
void addDestSubscriber(DestSubscriber sub, SubscriberListener listen) throws FTLException
FTLException
void removeDestSubscriber(DestSubscriber sub) throws FTLException
FTLException