rts/include/umlrtprioritymessagequeue.hh

// umlrtprioritymessagequeue.hh

/*******************************************************************************
* Copyright (c) 2014-2015 Zeligsoft (2009) Limited  and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*******************************************************************************/

#ifndef UMLRTPRIORITYMESSAGEQUEUE_HH
#define UMLRTPRIORITYMESSAGEQUEUE_HH

#include "umlrtinmessage.hh"
#include "umlrtmessagequeue.hh"
#include "umlrtsemaphore.hh"
#include "umlrtsignal.hh"
#include "umlrttimerqueue.hh"

struct UMLRTMessage;

// UMLRTPriorityMessageQueue - a collection of priority-message queues.

// This object has one message queue per priority level.

// The priority of each message is contained in the signal (within the message).

class UMLRTPriorityMessageQueue
{
public:

    UMLRTPriorityMessageQueue(const char * owner);

    // Return the queue associated with a priority.
    UMLRTMessageQueue & getQueue( UMLRTSignalElement::Priority priority );

    // Used to transfer all messages from each priority queue to
    // their associated priority-queue

    void moveAll( UMLRTPriorityMessageQueue & fromQueue );

    // Queue up all messages associated with timed-out timers.
    void queueTimerMessages( UMLRTTimerQueue * timerQueue );

    // Get the highest priority message from the collection of queues.
    UMLRTInMessage * dequeueHighestPriority();

    // Put the message into its appropriate priority-queue.
    void enqueue( UMLRTMessage * msg, bool front = false );

    // Return the notification file descriptor to indicate a message is ready.
    int getNotifyFd();

    // Clear notifications of pending messages. The message queues must be checked
    // after this call returns, ensuring no subsequent notification will be lost.
    void clearNotifyFd();

    // NOTE: isEmpty() is intended only for the sole consumer of the queue and
    // only reflects the emptiness of the queue at the time of calling.
    // Synchronization (i.e. the 'notify' mechanism) is required to ensure the
    // consumer will re-visit the queue when an item is queued.
    bool isEmpty();

    // Purge queue of elements that match the criteria.
    void remove( UMLRTQueue::match_compare_t callback, UMLRTQueue::match_notify_t notify, void * userData );

private:
    UMLRTPriorityMessageQueue();

    // Owner - for debugging.
    const char * const owner;

    // One message queue per priority.
    UMLRTMessageQueue queue[UMLRTSignalElement::PRIORITY_MAX];

    // Calling this causes the notification mechanism to be 'set'. Threads waiting
    // for notification on this queue will receive notification.
    void sendNotification();

    // Notification-pipe. Those waiting for an element to be queued can wait on select() on the
    // 'getNotifyFd()' (the read-end of the pipe).
    // Threads enqueuing messages write a byte to the pipe to notify waiting threads.
    // Clearing the notifications involves reading until the pipe is empty.
    int notifyFd[2];
};

#endif // UMLRTPRIORITYMESSAGEQUEUE_HH