TIBCO FTL®

Public Member Functions | List of all members
TIBCO.FTL.IEventQueue Interface Reference

Event queue objects hold message and timer events until listeners can process them. More...

Inheritance diagram for TIBCO.FTL.IEventQueue:

## Public Member Functions
void | AddSubscriber (ISubscriber subscriber, ISubscriberListener subListener)
| Add a subscriber to a queue. More...
long | Count ()
| Get the number of events in the queue. More...
IEventTimer | CreateTimer (double interval)
| Create and start a timer. More...
void | Dispatch ()
| Dispatch message events; wait indefinitely for an event. More...
void | Dispatch (double value)
| Dispatch message events; wait until timeout (in seconds) for an event. More...
void | DispatchNow ()
| Dispatch message events; do not wait. More...
string | Name ()
| Get the name of the event queue. More...
void | RemoveSubscriber (ISubscriber subscriber)
| Remove a subscriber from a queue. More...

## Detailed Description

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 and remove subscribers on a queue, create timers on a queue (and `Dispose` them), dispatch events from a queue, and stop a queue in preparation to `Dispose` it.

To create an event queue object, call IRealm.CreateEventQueue().

Best practice is to remove all subscribers before destroying the event queue.

Customers do not implement this interface.

## Member Function Documentation

## ◆ AddSubscriber()

void TIBCO.FTL.IEventQueue.AddSubscriber | ( | ISubscriber | subscriber,
|  | ISubscriberListener | subListener
| ) |  |

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 ISubscriberListener 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

  subscriber | The call adds this subscriber to the queue.
  subListener | Dispatching a message event invokes the callback method of this listener.

## ◆ Count()

long TIBCO.FTL.IEventQueue.Count | ( |  | ) |

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.

## ◆ CreateTimer()

IEventTimer TIBCO.FTL.IEventQueue.CreateTimer | ( | double | interval | ) |

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 `Dispose` the timer object.

Each time Dispatch() dispatches a timer event, the IEventTimer.Fired event fires.

Parameters

  interval | The timer places events on the queue at this repeating interval (in seconds).

Returns
  A new EventTimer object.

See also
  IEventTimer

## ◆ Dispatch() [1/2]

void TIBCO.FTL.IEventQueue.Dispatch | ( |  | ) |

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.

## ◆ Dispatch() [2/2]

void TIBCO.FTL.IEventQueue.Dispatch | ( | double | value | ) |

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

  value | 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.

## ◆ DispatchNow()

void TIBCO.FTL.IEventQueue.DispatchNow | ( |  | ) |

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.

## ◆ Name()

string TIBCO.FTL.IEventQueue.Name | ( |  | ) |

Get the name of the event queue.

Returns
  The name of the event queue.

## ◆ RemoveSubscriber()

void TIBCO.FTL.IEventQueue.RemoveSubscriber | ( | ISubscriber | subscriber | ) |

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

  subscriber | The call removes this subscriber from the queue.