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 | |
30 | namespace Poco { |
31 | |
32 | |
33 | class 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 | { |
54 | public: |
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 | |
128 | protected: |
129 | typedef std::multimap<Clock, Notification::Ptr> NfQueue; |
130 | Notification::Ptr dequeueOne(NfQueue::iterator& it); |
131 | bool wait(Clock::ClockDiff interval); |
132 | |
133 | private: |
134 | NfQueue _nfQueue; |
135 | Event _nfAvailable; |
136 | mutable FastMutex _mutex; |
137 | }; |
138 | |
139 | |
140 | } // namespace Poco |
141 | |
142 | |
143 | #endif // Foundation_TimedNotificationQueue_INCLUDED |
144 | |