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

List of all members, including inherited members

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

MessageQueueInterface()

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()
        , mQueue(NULL)
        , mOverrunFlag(false)
    {
        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) QUL_DECL_OVERRIDE
    {
        if (mQueue->isFull()) {
            // Discard message
            mOverrunFlag = true;
            return MessageQueueStatus::MessageDiscarded;
        }

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

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

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

    MessageQueueStatus receive(void *message, int32_t timeout = 0) QUL_DECL_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) QUL_DECL_OVERRIDE
    {
        (void) timeout; // This example does not implement timeout handling.

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

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

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

    bool isOverrun() const QUL_DECL_OVERRIDE { return mOverrunFlag; }

    void clearOverrun() QUL_DECL_OVERRIDE { mOverrunFlag = false; }

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

private:
    Private::CircularBuffer *mQueue;
    bool mOverrunFlag;
};

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

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

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

    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 LONG_MAX;
}

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