C

MessageQueueInterface Class

class Qul::Platform::MessageQueueInterface

Interface class providing platform-specific queues to Qt Quick Ultralite. More...

Header: #include <platform/messagequeue.h>
Since: Qt Quick Ultralite (Platform) 1.9

Public Functions

virtual ~MessageQueueInterface()
virtual uint32_t capacity() const = 0
virtual void clearOverrun() = 0
virtual bool discardSupported() const = 0
virtual Qul::Platform::MessageQueueStatus enqueueOrDiscard(const void *message) = 0
virtual Qul::Platform::MessageQueueStatus enqueueOrDiscardFromInterrupt(const void *message)
virtual Qul::Platform::MessageQueueStatus enqueueOrOverwrite(const void *message) = 0
virtual Qul::Platform::MessageQueueStatus enqueueOrOverwriteFromInterrupt(const void *message)
virtual bool isEmpty() const = 0
virtual bool isEmptyFromInterrupt() const
virtual bool isOverrun() const = 0
virtual bool overwriteSupported() const = 0
virtual Qul::Platform::MessageQueueStatus receive(void *message, int32_t timeout = 0) = 0
virtual Qul::Platform::MessageQueueStatus receiveFromInterrupt(void *message, int32_t timeout = 0)

Protected Functions

Detailed Description

Qt Quick Ultralite uses this interface to implement queues for EventQueues. It is useful when you have your own queue implementation (or an OS provided one), which is preferred over the default implementation provided by Qt Quick Ultralite.

By default, enqueueOrDiscardFromInterrupt(), enqueueOrOverwriteFromInterrupt(), and receiveFromInterrupt() are calling their respective non-interrupt versions. These must be overridden unless the underlying queue functionality is interrupt-safe or measures are taken to ensure interrupt-safety.

Support for discarding and/or overwriting is signalled by returning a boolean from the discardSupported() and overwriteSupported() functions.

Note: One or both of these operations must be supported to ensure that the EventQueue functions as expected.

Example

The MessageQueueInterface is implemented using a simple circular buffer.

The queue implementation does not support overwriting, so all messages that cannot be pushed to the queue is discarded.

The subclass could look like this:

class MyMessageQueue : public MessageQueueInterface
{
public:
    MyMessageQueue(const uint32_t &capacity, const uint32_t &messageSize)
        : MessageQueueInterface()
    {
        void *memory = qul_malloc(sizeof(Private::CircularBuffer));
        mQueue = new (memory) Private::CircularBuffer(capacity, messageSize);
    }

    ~MyMessageQueue()
    {
        mQueue->~CircularBuffer();
        qul_free(mQueue);
    }

    MessageQueueStatus enqueueOrDiscard(const void *message) override
    {
        if (mQueue->isFull()) {
            // Discard message
            mOverrunFlag = true;
            return MessageQueueStatus::MessageDiscarded;
        }

        mQueue->pushBack(message);
        return MessageQueueStatus::Success;
    }

    MessageQueueStatus enqueueOrDiscardFromInterrupt(const void *message) override
    {
        // disableInterrupts();
        auto state = enqueueOrDiscard(message);
        // enableInterrupts();
        return state;
    }

    MessageQueueStatus enqueueOrOverwrite(const void *message) override
    {
        return MessageQueueStatus::OverwriteNotSupported;
    }

    MessageQueueStatus receive(void *message, int32_t timeout = 0) override
    {
        (void) timeout; // This example does not implement timeout handling.

        if (mQueue->isEmpty())
            return MessageQueueStatus::EmptyQueue;

        mQueue->popFront(message);
        return MessageQueueStatus::Success;
    }

    MessageQueueStatus receiveFromInterrupt(void *message, int32_t timeout = 0) override
    {
        (void) timeout; // This example does not implement timeout handling.

        // disableInterrupts();
        auto state = receive(message);
        // enableInterrupts();
        return state;
    }

    bool discardSupported() const override { return true; }
    bool overwriteSupported() const override { return false; }

    bool isEmpty() const override { return mQueue->isEmpty(); }
    bool isEmptyFromInterrupt() const override
    {
        // disableInterrupts();
        return isEmpty();
        // enableInterrupts();
    }

    bool isOverrun() const override { return mOverrunFlag; }

    void clearOverrun() override { mOverrunFlag = false; }

    uint32_t capacity() const override { return mQueue->capacity(); }

private:
    Private::CircularBuffer *mQueue = nullptr;
    bool mOverrunFlag = false;
};

After this, implement the Qul::Platform::requestQueue() function:

MessageQueueInterface *requestQueue(size_t queueCapacity, size_t messageSize)
{
    void *queue = qul_malloc(sizeof(MyMessageQueue));

    if (queue == nullptr) {
        return nullptr;
    }

    MessageQueueInterface *interface = new (queue) MyMessageQueue(queueCapacity, messageSize);
    return interface;
}

In addition, implement the Qul::Platform::deleteQueue() function:

void deleteQueue(MessageQueueInterface *queue)
{
    MyMessageQueue *mq = static_cast<MyMessageQueue *>(queue);
    mq->~MyMessageQueue();
    qul_free(mq);
}

Finally, implement Qul::Platform::maxQueueMessageSize():

size_t maximumQueueMessageSize()
{
    return SIZE_MAX;
}

See also Qul::Platform::MessageQueue and Qul::EventQueue.

Member Function Documentation

[protected, since Qt Quick Ultralite (Platform) 1.9] MessageQueueInterface::MessageQueueInterface()

Constructs MessageQueueInterface.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also ~MessageQueueInterface().

[virtual, since Qt Quick Ultralite (Platform) 1.9] MessageQueueInterface::~MessageQueueInterface()

Destructs the MessageQueueInterface class instance.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also MessageQueueInterface().

[pure virtual, since Qt Quick Ultralite (Platform) 1.9] uint32_t MessageQueueInterface::capacity() const

Returns the maximum number of items the queue can hold.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

[pure virtual, since Qt Quick Ultralite (Platform) 1.9] void MessageQueueInterface::clearOverrun()

Clears the overrun state of the queue.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also isOverrun().

[pure virtual, since Qt Quick Ultralite (Platform) 1.9] bool MessageQueueInterface::discardSupported() const

Returns true if discarding is supported. This means enqueueOrDiscard() and enqueueOrDiscardFromInterrupt() can be used.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also overwriteSupported(), enqueueOrDiscard(), and enqueueOrDiscardFromInterrupt().

[pure virtual, since Qt Quick Ultralite (Platform) 1.9] Qul::Platform::MessageQueueStatus MessageQueueInterface::enqueueOrDiscard(const void *message)

Adds message to the queue or discards it if the queue is full. Returns MessageQueueStatus indicating the result of the function call.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also enqueueOrDiscardFromInterrupt(), discardSupported(), receive(), receiveFromInterrupt(), and enqueueOrOverwrite().

[virtual, since Qt Quick Ultralite (Platform) 1.9] Qul::Platform::MessageQueueStatus MessageQueueInterface::enqueueOrDiscardFromInterrupt(const void *message)

Adds message to the queue or discards it if the queue is full. It is similar to enqueueOrDiscard(), but interrupt-safe. The default implementation calls enqueueOrDiscard() with message.

Returns MessageQueueStatus indicating the result of the function call.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also enqueueOrDiscard(), discardSupported(), receive(), receiveFromInterrupt(), and enqueueOrOverwriteFromInterrupt().

[pure virtual, since Qt Quick Ultralite (Platform) 1.9] Qul::Platform::MessageQueueStatus MessageQueueInterface::enqueueOrOverwrite(const void *message)

Adds message or overwrites the last item in the queue if the queue is full. Returns MessageQueueStatus indicating the result of the function call.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also enqueueOrOverwriteFromInterrupt(), overwriteSupported(), receive(), receiveFromInterrupt(), and enqueueOrDiscard().

[virtual, since Qt Quick Ultralite (Platform) 1.9] Qul::Platform::MessageQueueStatus MessageQueueInterface::enqueueOrOverwriteFromInterrupt(const void *message)

Adds message or overwrites the last item in the queue if the queue is full. It is similar to enqueueOrOverwrite(), but interrupt-safe. The default implementation calls enqueueOrOverwrite() with message.

Returns MessageQueueStatus indicating the result of the function call.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also enqueueOrOverwrite(), overwriteSupported(), receive(), receiveFromInterrupt(), and enqueueOrDiscardFromInterrupt().

[pure virtual, since Qt Quick Ultralite (Platform) 1.9] bool MessageQueueInterface::isEmpty() const

Returns true if the queue is empty, or false otherwise.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also isEmptyFromInterrupt().

[virtual, since Qt Quick Ultralite (Platform) 1.9] bool MessageQueueInterface::isEmptyFromInterrupt() const

Returns true if the queue is empty, or false otherwise. It is similar to isEmpty() but interrupt-safe.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also isEmpty().

[pure virtual, since Qt Quick Ultralite (Platform) 1.9] bool MessageQueueInterface::isOverrun() const

Returns true if the queue is overrun by items that are either discarded or overwritten.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also clearOverrun().

[pure virtual, since Qt Quick Ultralite (Platform) 1.9] bool MessageQueueInterface::overwriteSupported() const

Returns true if overwriting is supported. This means enqueueOrOverwrite() and enqueueOrOverwriteFromInterrupt() can be used.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also discardSupported(), enqueueOrOverwrite(), and enqueueOrOverwriteFromInterrupt().

[pure virtual, since Qt Quick Ultralite (Platform) 1.9] Qul::Platform::MessageQueueStatus MessageQueueInterface::receive(void *message, int32_t timeout = 0)

Returns the first message from the queue. On success, message must contain the popped message and MessageQueueStatus::Success. On failure, an appropriate error MessageQueueStatus must be returned, along with a null pointer. If timeout is specified, the function must return after timeout milliseconds. A zero timeout value means that the function does not block at all, and a negative value means that the function waits infinitely.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also receiveFromInterrupt(), enqueueOrDiscard(), enqueueOrDiscardFromInterrupt(), enqueueOrOverwrite(), and enqueueOrOverwriteFromInterrupt().

[virtual, since Qt Quick Ultralite (Platform) 1.9] Qul::Platform::MessageQueueStatus MessageQueueInterface::receiveFromInterrupt(void *message, int32_t timeout = 0)

Returns the first message from the queue. It is similar to receive(), but interrupt-safe. The default implementation calls receive(). Both message and timeout are used like in receive(), although timeout must not be used when handling queues from interrupt.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also receive(), enqueueOrDiscard(), enqueueOrDiscardFromInterrupt(), enqueueOrOverwrite(), and enqueueOrOverwriteFromInterrupt().

Available under certain Qt licenses.
Find out more.