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.c - (right-click and save as "event_q_rcv.c") main program.

Program explanation: event_q_rcv.c

Creating the Event Queue

The eventQ is initialized by calling lbm_event_queue_create with no other arguments:

00087      err = lbm_event_queue_create(&evq, NULL, NULL, NULL);

Create a receiver with an event queue.

To "hook up" a receiver to an event queue, simply pass it into the receive create function. Note that all further events will be delivered to the event queue. They will not be processed until lbm_event_dispatch is called with the event queue.

00093      err = lbm_rcv_create(&rcv, ctx, rtopic, rcv_handle_msg, NULL, evq);

Processing Events on the Event Queue

To run an event queue on a specific thread, simply call lbm_event_dispatch() with an argument (time in milliseconds). This will execute events on the event queue on the thread that called lbm_event_dispatch for the specified amount of time. In this case the main() thread will execute events for 10 seconds.

00099      err = lbm_event_dispatch(evq, 10000);
00100      if (err == LBM_FAILURE) {

Cleanup

When using an event queue, care must be taken in order to cleanly shut down. Issues can potentially occur if a context tries to deliver events to the queue after it has already been _delete()'ed. Therefore, the application should delete 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, the event queue can safely be delete()'ed.

00105      err = lbm_rcv_delete(rcv);
00106      EX_LBM_CHK(err);
00107      err = lbm_context_delete(ctx);
00108      EX_LBM_CHK(err);
00109      err = lbm_event_queue_delete(evq);
00110      EX_LBM_CHK(err);