File Information
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 
typedef std::multimap < Clock, Notification::Ptr > NfQueue;
Constructors
TimedNotificationQueue
Creates the TimedNotificationQueue.
Destructor
~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 iff 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.
enqueueNotification
void enqueueNotification(
Notification::Ptr pNotification,
Clock clock
);
Enqueues the given notification by adding it to the queue according to the given clock value. Lower clock 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.
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
Notification::Ptr dequeueOne(
NfQueue::iterator & it
);
wait
bool wait(
Clock::ClockDiff interval
);