C

EventQueue Class

template <typename EventType_, Qul::EventQueueOverrunPolicy overrunPolicy, size_t queueSize> class Qul::EventQueue

Provides a convenient way to send and receive events across different parts of the application. More...

Header: #include <qul/eventqueue.h>
Since: Qt Quick Ultralite 1.0

Public Types

Public Functions

EventQueue()
~EventQueue()
virtual void onEvent(const Qul::EventQueue::EventType &event) = 0
virtual void onQueueOverrun()
void postEvent(const Qul::EventQueue::EventType &event)

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.

Events can be posted to the queue using the postEvent function from any part of the application, including interrupt handlers. Override onEvent to process the events, typically during the next frame.

EventQueue is supposed to be interrupt-safe as long as there is only a single writer, because writes and reads are directed to different lists. postEvent() can be called from an interrupt when there is only one one writer to a queue. If there are multiple writers it has to be made sure that postEvent() is not itself interrupted by another postEvent() to the same queue. process() is safe to be interrupted by postEvent().

When a queue receives more events than it can hold, they are handled according to the EventQueueOverrunPolicy. Additionally onQueueOverrun will be called before the next batch of events is processed.

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 anywhere:

integerEventQueue.postEvent(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_OverwriteLast, 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);
    }
};

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.

See also Transferring data from Interrupt Handlers to QML.

Member Type Documentation

EventQueue::EventType

Type of event used for this EventLoop.

Member Function Documentation

EventQueue::EventQueue()

Constructs the queue and registers it with the application for event processing.

EventQueue::~EventQueue()

Destructs the queue and unregisters it.

[pure virtual] void EventQueue::onEvent(const Qul::EventQueue::EventType &event)

A derived class must override this method to process event.

Events are processed from oldest to newest in each queue.

[virtual] void EventQueue::onQueueOverrun()

A derived class may override this method to handle queue overrun.

This function is called if more events were posted to this queue than fit the allocated storage. It is not called immediately during the postEvent call, but rather directly before the next batch of onEvent calls.

void EventQueue::postEvent(const Qul::EventQueue::EventType &event)

Appends a copy of event to the queue to schedule it for processing during the next dispatch operation (typically the next frame).

If the queue is full, the EventQueueOverrunPolicy determines whether the event is discarded or overwrites an old event. In both cases, a call of onQueueOverrun is scheduled.

Available under certain Qt licenses.
Find out more.