Interface EventQueue

public interface EventQueue
Event queue objects hold message and timer events until listeners can process them.

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.

  • Field Details

    • PROPERTY_BOOL_INLINE_MODE

      static final String PROPERTY_BOOL_INLINE_MODE
      Inline mode (low-latency); boolean.

      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.

      See Also:

    • PROPERTY_INT_DISCARD_POLICY

      static final String PROPERTY_INT_DISCARD_POLICY
      Discard policy; integer.

      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:

      See Also:

    • PROPERTY_INT_DISCARD_POLICY_MAX_EVENTS

      static final String PROPERTY_INT_DISCARD_POLICY_MAX_EVENTS
      Max events; integer.

      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.

      See Also:

    • PROPERTY_INT_DISCARD_POLICY_DISCARD_AMOUNT

      static final String PROPERTY_INT_DISCARD_POLICY_DISCARD_AMOUNT
      Discard amount; integer.

      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.

      See Also:

    • PROPERTY_STRING_NAME

      static final String PROPERTY_STRING_NAME
      Queue name; string.

      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.

      See Also:

    • DISCARD_NONE

      static final int DISCARD_NONE
      Do not discard events (default behavior).
      See Also:

    • DISCARD_OLD

      static final int DISCARD_OLD
      Discard old events from the head of the queue.
      See Also:

    • DISCARD_NEW

      static final int DISCARD_NEW
      Discard new events, instead of adding them to the queue.
      See Also:

  • Method Details

    • addSubscriber

      void addSubscriber(Subscriber sub, SubscriberListener listen) throws FTLException
      Add a subscriber to a queue.

      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.

      Parameters:
      sub - The call adds this subscriber to the queue.
      listen - Dispatching a message event invokes the callback method of this listener.
      Throws:
      FTLException

    • removeSubscriber

      void removeSubscriber(Subscriber sub) throws FTLException
      Remove a subscriber from a queue.

      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.

      Parameters:
      sub - The call removes this subscriber from the queue.
      Throws:
      FTLException

    • createTimer

      EventTimer createTimer(double interval, EventTimerListener listen) throws FTLException
      Create and start a timer.

      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.

      Parameters:
      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.
      Returns:
      a new EventTimer object
      Throws:
      FTLException

    • destroyTimer

      void destroyTimer(EventTimer timer) throws FTLException
      Stop and destroy a timer.

      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.

      Parameters:
      timer - The call stops this timer.
      Throws:
      FTLException

    • dispatch

      void dispatch() throws FTLException
      Dispatch message events; wait indefinitely for an event.

      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.

      Throws:
      FTLException

    • dispatch

      void dispatch(long timeout, TimeUnit units) throws FTLException
      Dispatch message events; wait until timeout for an event.

      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.

      Parameters:
      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.
      Throws:
      FTLException

    • dispatch

      void dispatch(double seconds) throws FTLException
      Dispatch message events; wait until timeout (in seconds) for an event.

      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.

      Parameters:
      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.
      Throws:
      FTLException

    • dispatchNow

      void dispatchNow() throws FTLException
      Dispatch message events; do not wait.

      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.

      Throws:
      FTLException

    • destroy

      void destroy() throws FTLException
      Destroy an event queue.

      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.

      Throws:
      FTLException

    • count

      long count() throws FTLException
      Get the number of events in the queue.

      The count includes both message events and timer events.

      Returns:
      The number of events in the queue.
      Throws:
      FTLException

    • name

      String name()
      Return the name of the event queue object.
      Returns:
      The name of the event queue object.
      Since:
      6.5

    • addDestSubscriber

      void addDestSubscriber(DestSubscriber sub, SubscriberListener listen) throws FTLException
      Add a destination subscriber to the event queue
      Throws:
      FTLException
      Since:
      7.1

    • removeDestSubscriber

      void removeDestSubscriber(DestSubscriber sub) throws FTLException
      Remove a destination subscriber from the event queue
      Throws:
      FTLException
      Since:
      7.1