Poco

class TimedNotificationQueue

Library: Foundation
Package: Notifications
Header: Poco/TimedNotificationQueue.h

Description

A TimedNotificationQueue object provides a way to implement timed, asynchronous notifications. This is especially useful for sending notifications from one thread to another, for example from a background thread to the main (user interface) thread.

The TimedNotificationQueue is quite similar to the NotificationQueue class. The only difference to NotificationQueue is that each Notification is tagged with a Timestamp. When inserting a Notification into the queue, the Notification is inserted according to the given Timestamp, with lower Timestamp values being inserted before higher ones.

Notifications are dequeued in order of their timestamps.

TimedNotificationQueue has some restrictions regarding multithreaded use. While multiple threads may enqueue notifications, only one thread at a time may dequeue notifications from the queue.

If two threads try to dequeue a notification simultaneously, the results are undefined.

Member Summary

Member Functions: clear, dequeueNotification, dequeueOne, empty, enqueueNotification, size, wait, waitDequeueNotification

Types

NfQueue protected

typedef std::multimap < Timestamp, Notification::Ptr > NfQueue;

Constructors

TimedNotificationQueue

TimedNotificationQueue();

Creates the TimedNotificationQueue.

Destructor

~TimedNotificationQueue

~TimedNotificationQueue();

Destroys the TimedNotificationQueue.

Member Functions

clear

void clear();

Removes all notifications from the queue.

Calling clear() while another thread executes one of the dequeue member functions will result in undefined behavior.

dequeueNotification

Notification * dequeueNotification();

Dequeues the next pending notification with a timestamp less than or equal to the current time. Returns 0 (null) if no notification is available. The caller gains ownership of the notification and is expected to release it when done with it.

It is highly recommended that the result is immediately assigned to a Notification::Ptr, to avoid potential memory management issues.

empty

bool empty() const;

Returns true if and only if the queue is empty.

enqueueNotification

void enqueueNotification(
    Notification::Ptr pNotification,
    Timestamp timestamp
);

Enqueues the given notification by adding it to the queue according to the given timestamp. Lower timestamp values are inserted before higher ones. The queue takes ownership of the notification, thus a call like

notificationQueue.enqueueNotification(new MyNotification, someTime);

does not result in a memory leak.

size

int size() const;

Returns the number of notifications in the queue.

waitDequeueNotification

Notification * waitDequeueNotification();

Dequeues the next pending notification. If no notification is available, waits for a notification to be enqueued. The caller gains ownership of the notification and is expected to release it when done with it. This method returns 0 (null) if wakeUpWaitingThreads() has been called by another thread.

It is highly recommended that the result is immediately assigned to a Notification::Ptr, to avoid potential memory management issues.

waitDequeueNotification

Notification * waitDequeueNotification(
    long milliseconds
);

Dequeues the next pending notification. If no notification is available, waits for a notification to be enqueued up to the specified time. Returns 0 (null) if no notification is available. The caller gains ownership of the notification and is expected to release it when done with it.

It is highly recommended that the result is immediately assigned to a Notification::Ptr, to avoid potential memory management issues.

dequeueOne protected

Notification::Ptr dequeueOne(
    NfQueue::iterator & it
);

wait protected

bool wait(
    Timestamp::TimeDiff interval
);