How to use an Event Queue with a receiver

An event queue is an object in the UM library that allows a receiver to process events on an application thread. By default all events are processed on the context thread. This context thread is created automatically when the context object is instantiated. This thread is a shared resource between all sources, receivers and timers, both internally in the UM library and externally in the application. This can quickly become a bottleneck if an application is doing lots of things, like receiving messages, tracking timers related to UMP, or event getting lots of other events related to the UM library. Therefore, at a slight cost to performance (1 thread switch), an application can use its own thread, or as many as it likes. One way to do this is to use the event queue.

There is one program source file:

• event_q_rcv.java - (right-click and save as "event_q_rcv.java") main program.

Program explanation: event_q_rcv.java

Creating the Event Queue

The eventQ is simply an LBMEventQueue object that is constructed with no arguments.

00012          evq = new LBMEventQueue();

Create a receiver with an event queue.

To "hook up" a receiver to an event queue, simply pass it into the constructor. Note that all further events will be delivered to the event queue. They will not be processed until the event queue is .run().

00019              /* The event queue object is passed into the receiver constructor */
00020              /* This causes events to be queued in an unbounded Q.  In order   */
00021              /* to process these messages the evq.Run() method must be called  */
00022              rcv = new LBMReceiver(ctx, topic, rcvCB, null, evq);

Processing Events on the Event Queue

To run an event queue on a specific thread, simply call .run() with an argument (time in miliseconds). This will execute events on the event queue on the thread that called .run() for the specified amount of time.

00030          evq.run(60000);

Cleanup

When using an event queue, care must be taken in order to cleanly shutdown. Issues can potentially occur if a context tries to deliver events to the queue after it has already been .close()d. Therefore, the application should shut down all receivers, then the context itself. This will prevent any new events from being generated. Once the queue is empty and no new events are being generated, it can safely be .close()d.

00035              rcv.close();
00036              ctx.close();
00037              evq.close();