Threading and the SystemQueue

Ariba makes it easy to avoid threading issues like synchronization and upcoming problems like deadlocks, race conditions, or access violations. The threading model in Ariba is completely serial, parallelism is avoided whenever possible. If you are using Ariba to write a service or application, two simple guidelines apply:

• Code event driven
• Don't block or wait

When you comply with these two points, you will never get into any threading problems!

Overview of Threading in Ariba

Ariba runs one main thread, called the SystemQueue. All events in Ariba originate the SystemQueue, that means that all functionality is triggered by events that are placed into the SystemQueue. As all functionality is triggerd through the SystemQueue, only one thread exists in Ariba and you can be sure that all code always runs in sync. The concept of one main queue exists in several software projects, and in gernal is called ​Event loop:

• MS Windows uses one main thread in GUI applications (also called the main loop) to schedule and execute GUI changes (details on this are available ​here. The WinMain function in Windows applications that are linked against the Windows Subsystem is such an event loop. It uses the Win32 API GetMessage, TranslateMessage, and DispatchMessage to implement serial message processing in Windows.
• OMNeT++ has an event queue that completely handles execution of simulations (called ​cScheduler. If you compile Ariba with simulation support, the SystemQueue gets synchronized with the OMNeT++ event queue for seamless integration.
• The X Windows System uses event queues in XLib and GLib.

SystemQueue Internals

The SystemQueue class has one main thread that uses boost::condition with the wait and signal functionality to implement a queue. The thread blocks and waits until a new event is inserted into the queue. It then executes this event and calls the event handler that is assigned to this event. The insertion and execution of an event therefore are decoupled in terms of threading and run asynchronous.

One example of events are imcoming network messages. When a packet comes in from the network a new event is generated and the packet attacked to this event. The event is inserted into the SystemQueue and gets processed asynchronous from the SystemQueue thread.

Using the SystemQueue

Every mechanisms that gets triggered by some external event must get synchronized with the main SystemQueue thread. If you e.g. observe the network card and want to execute some stuff on network changes, you must synchronized with the SystemQueue. Why? Because a network packet might get processed and call some code that you would maybe call, too. Therefore producing parallel access to some code and causing threading problems.

Synchronizing with the main Ariba thread is easy, thanks to the SystemQueue. We will not explain step-by-step how to use the SystemQueue in your code:

1. In you .h file integrate the SystemQueue header and some using declerations;

#include "spovnet/common/system/SystemQueue.h"
using spovnet::common::SystemQueue;
using spovnet::common::SystemEvent;
using spovnet::common::SystemEventType;
using spovnet::common::SystemEventListener;

2. Derive your class from from a SystemEventListener to be able to receive events:

class MyClass : public SystemEventListener

3. Redefine the SystemEventListener interface:

protected:
    virtual void handleSystemEvent( const SystemEvent& event );

Using Blocking Code