1//
2// TimedNotificationQueue.h
3//
4// Library: Foundation
5// Package: Notifications
6// Module: TimedNotificationQueue
7//
8// Definition of the TimedNotificationQueue class.
9//
10// Copyright (c) 2009, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef Foundation_TimedNotificationQueue_INCLUDED
18#define Foundation_TimedNotificationQueue_INCLUDED
19
20
21#include "Poco/Foundation.h"
22#include "Poco/Notification.h"
23#include "Poco/Mutex.h"
24#include "Poco/Event.h"
25#include "Poco/Timestamp.h"
26#include "Poco/Clock.h"
27#include <map>
28
29
30namespace Poco {
31
32
33class Foundation_API TimedNotificationQueue
34 /// A TimedNotificationQueue object provides a way to implement timed, asynchronous
35 /// notifications. This is especially useful for sending notifications
36 /// from one thread to another, for example from a background thread to
37 /// the main (user interface) thread.
38 ///
39 /// The TimedNotificationQueue is quite similar to the NotificationQueue class.
40 /// The only difference to NotificationQueue is that each Notification is tagged
41 /// with a Timestamp. When inserting a Notification into the queue, the
42 /// Notification is inserted according to the given Timestamp, with
43 /// lower Timestamp values being inserted before higher ones.
44 ///
45 /// Notifications are dequeued in order of their timestamps.
46 ///
47 /// TimedNotificationQueue has some restrictions regarding multithreaded use.
48 /// While multiple threads may enqueue notifications, only one thread at a
49 /// time may dequeue notifications from the queue.
50 ///
51 /// If two threads try to dequeue a notification simultaneously, the results
52 /// are undefined.
53{
54public:
55 TimedNotificationQueue();
56 /// Creates the TimedNotificationQueue.
57
58 ~TimedNotificationQueue();
59 /// Destroys the TimedNotificationQueue.
60
61 void enqueueNotification(Notification::Ptr pNotification, Timestamp timestamp);
62 /// Enqueues the given notification by adding it to
63 /// the queue according to the given timestamp.
64 /// Lower timestamp values are inserted before higher ones.
65 /// The queue takes ownership of the notification, thus
66 /// a call like
67 /// notificationQueue.enqueueNotification(new MyNotification, someTime);
68 /// does not result in a memory leak.
69 ///
70 /// The Timestamp is converted to an equivalent Clock value.
71
72 void enqueueNotification(Notification::Ptr pNotification, Clock clock);
73 /// Enqueues the given notification by adding it to
74 /// the queue according to the given clock value.
75 /// Lower clock values are inserted before higher ones.
76 /// The queue takes ownership of the notification, thus
77 /// a call like
78 /// notificationQueue.enqueueNotification(new MyNotification, someTime);
79 /// does not result in a memory leak.
80
81 Notification* dequeueNotification();
82 /// Dequeues the next pending notification with a timestamp
83 /// less than or equal to the current time.
84 /// Returns 0 (null) if no notification is available.
85 /// The caller gains ownership of the notification and
86 /// is expected to release it when done with it.
87 ///
88 /// It is highly recommended that the result is immediately
89 /// assigned to a Notification::Ptr, to avoid potential
90 /// memory management issues.
91
92 Notification* waitDequeueNotification();
93 /// Dequeues the next pending notification.
94 /// If no notification is available, waits for a notification
95 /// to be enqueued.
96 /// The caller gains ownership of the notification and
97 /// is expected to release it when done with it.
98 ///
99 /// It is highly recommended that the result is immediately
100 /// assigned to a Notification::Ptr, to avoid potential
101 /// memory management issues.
102
103 Notification* waitDequeueNotification(long milliseconds);
104 /// Dequeues the next pending notification.
105 /// If no notification is available, waits for a notification
106 /// to be enqueued up to the specified time.
107 /// Returns 0 (null) if no notification is available.
108 /// The caller gains ownership of the notification and
109 /// is expected to release it when done with it.
110 ///
111 /// It is highly recommended that the result is immediately
112 /// assigned to a Notification::Ptr, to avoid potential
113 /// memory management issues.
114
115 bool empty() const;
116 /// Returns true iff the queue is empty.
117
118 int size() const;
119 /// Returns the number of notifications in the queue.
120
121 void clear();
122 /// Removes all notifications from the queue.
123 ///
124 /// Calling clear() while another thread executes one of
125 /// the dequeue member functions will result in undefined
126 /// behavior.
127
128protected:
129 typedef std::multimap<Clock, Notification::Ptr> NfQueue;
130 Notification::Ptr dequeueOne(NfQueue::iterator& it);
131 bool wait(Clock::ClockDiff interval);
132
133private:
134 NfQueue _nfQueue;
135 Event _nfAvailable;
136 mutable FastMutex _mutex;
137};
138
139
140} // namespace Poco
141
142
143#endif // Foundation_TimedNotificationQueue_INCLUDED
144