Detailed Description

This is a template class that requires type of the event, EventQueueOverrunPolicy, and maximum size of the queue. The defaults are EventQueueOverrunPolicy_Discard and a queue size of 5. See Adjusting the Queue Size for details.

In general, events can be posted to the queue using the postEvent function when not in interrupt context, or using the postEventFromInterrupt function from an interrupt handler. Override onEvent to process the events, typically during the next frame.

DoubleQueue is the default queue backend on baremetal platforms. It is interrupt-safe as long as there is a single writer, because writes and reads are directed to different lists. postEventFromInterrupt() can be called from an interrupt when there is a single writer to a queue. If there are multiple writers, you must ensure that postEvent() or postEventFromInterrupt() are not interrupted by another postEvent() or postEventFromInterrupt() to the same queue. process() is safe to be interrupted by postEvent() or postEventFromInterrupt().

On embedded platforms that have support for std::thread and std::mutex, the queue is thread-safe by using mutexes.

For RTOS-based platforms, the implementation of queue backend is based on RTOS-specific queues, which makes the Qul::EventQueue thread-safe in a multi-threaded environment.

The default backends provided by Qt Quick Ultralite use memcpy() or equivalent to copy the data to the queue. This means that the datatypes used in the EventQueue must be/contain POD, or plain old data. If this cannot be done, pointers must be used instead. However, backends provided by Qt Quick Ultralite do not manage memory when the events are pointers. You must either use EventQueueOverrunPolicy_Discard and onEventDiscarded, or provide a custom backend to handle memory for events that are overwritten. See Implementing custom queues for more information.

When a queue receives more events than it can hold, they are handled according to the EventQueueOverrunPolicy. Additionally, onQueueOverrun is called before processing any event as long as the state is not reset by calling clearOverrun.

If EventQueueOverrunPolicy_Discard is used and discarded events need additional handling, onEventDiscarded function can be overridden.

Example

Derive from EventQueue to create a queue for a particular event type and override onEvent:

#include <qul/eventqueue.h>

typedef int IntegerEvent;

class IntegerEventQueue : public Qul::EventQueue<IntegerEvent> {
    void onEvent(const IntegerEvent &event) override {
        // do some stuff with your event here
    }
};

Next, create an instance of the queue. Queues that expose data or signals to QML are often derived from Singleton in addition to EventQueue, making this step unnecessary.

IntegerEventQueue integerEventQueue;

Now, events can be posted from outside of interrupt context:

integerEventQueue.postEvent(42);

Or from interrupt handlers:

integerEventQueue.postEventFromInterrupt(42);

Adjusting the Queue Size

By default, size of the queue is set to 5. The size determines how many events can be stored between subsequent dispatch operations. Dispatching is performed as soon as possible, typically in the next application frame. Use the EventQueueOverrunPolicy to control how the queue behaves when it is full.

// A queue where only the most recent event is interesting
Qul::EventQueue<IntegerEvent, Qul::EventQueueOverrunPolicy_OverwriteOldest, 1>

// A queue that can store many events
Qul::EventQueue<IntegerEvent, Qul::EventQueueOverrunPolicy_Discard, 1000>

Override the onQueueOverrun method to get notified of overruns.

class AudioQueue : public Qul::EventQueue<float, Qul::EventQueueOverrunPolicy_Discard, 1000>
{
    void onQueueOverrun() override {
        // Avoid the problem by reducing the frequency of event generation.
        setSampleRate(8000);
        clearOverrun();
    }
};

Event Ordering

The order of events in each queue is preserved but no order is guaranteed between different queues.

This can be a problem when the order of events matters, such as for input events:

keyboardInput.postEvent(KeyEvents(...));
touchInput.postEvent(TouchEvent(...));
// Unknown whether the KeyEvent or TouchEvent is processed first!

In these cases, use a single queue with a union or std::variant event type instead of separate queues.