1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Class Poco::NotificationQueue</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<meta name="author" content="Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="publisher" content="Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="copyright" content="Copyright (c) 2009, Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="language" content="en"/>
<meta name="date" content="2009-11-24"/>
<meta name="generator" content="PocoDoc"/>
<link rel="stylesheet" href="css/styles.css" type="text/css"/>
</head>
<body bgcolor="#ffffff" leftmargin="0" topmargin="0">
<div class="header">
<h1 class="namespace"><a href="Poco.html" class="namespace">Poco</a></h1>
<h1 class="symbol">class NotificationQueue</h1>
</div>
<div class="body">
<p>
<b>Library:</b> Foundation<br />
<b>Package:</b> Notifications<br />
<b>Header:</b> Poco/NotificationQueue.h</p>
<h2>Description</h2>
<div class="description">
<p>A <a href="Poco.NotificationQueue.html" title="class Poco::NotificationQueue">NotificationQueue</a> object provides a way to implement 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. </p>
<p>The <a href="Poco.NotificationQueue.html" title="class Poco::NotificationQueue">NotificationQueue</a> can also be used to distribute work from a controlling thread to one or more worker threads. Each worker thread repeatedly calls <a href="Poco.NotificationQueue.html#8814" title="Poco::NotificationQueue::waitDequeueNotification()">waitDequeueNotification</a>() and processes the returned notification. Special care must be taken when shutting down a queue with worker threads waiting for notifications. The recommended sequence to shut down and destroy the queue is to </p>
<ol>
<li>set a termination flag for every worker thread </li>
<li>call the <a href="Poco.NotificationQueue.html#8819" title="Poco::NotificationQueue::wakeUpAll()">wakeUpAll</a>() method </li>
<li>join each worker thread </li>
<li>destroy the notification queue. </li>
</ol>
</div>
<h2>Member Summary</h2>
<p><b>Member Functions: </b><a href="Poco.NotificationQueue.html#8822" title="Poco::NotificationQueue::clear()">clear</a>, <a href="Poco.NotificationQueue.html#8824" title="Poco::NotificationQueue::defaultQueue()">defaultQueue</a>, <a href="Poco.NotificationQueue.html#8813" title="Poco::NotificationQueue::dequeueNotification()">dequeueNotification</a>, <a href="Poco.NotificationQueue.html#8825" title="Poco::NotificationQueue::dequeueOne()">dequeueOne</a>, <a href="Poco.NotificationQueue.html#8817" title="Poco::NotificationQueue::dispatch()">dispatch</a>, <a href="Poco.NotificationQueue.html#8820" title="Poco::NotificationQueue::empty()">empty</a>, <a href="Poco.NotificationQueue.html#8809" title="Poco::NotificationQueue::enqueueNotification()">enqueueNotification</a>, <a href="Poco.NotificationQueue.html#8811" title="Poco::NotificationQueue::enqueueUrgentNotification()">enqueueUrgentNotification</a>, <a href="Poco.NotificationQueue.html#8823" title="Poco::NotificationQueue::hasIdleThreads()">hasIdleThreads</a>, <a href="Poco.NotificationQueue.html#8821" title="Poco::NotificationQueue::size()">size</a>, <a href="Poco.NotificationQueue.html#8814" title="Poco::NotificationQueue::waitDequeueNotification()">waitDequeueNotification</a>, <a href="Poco.NotificationQueue.html#8819" title="Poco::NotificationQueue::wakeUpAll()">wakeUpAll</a></p>
<h2>Constructors</h2>
<h3><a name="8807">NotificationQueue</a></h3>
<p class="decl"><a href="Poco.NotificationQueue.html" title="class Poco::NotificationQueue">NotificationQueue</a>();</p>
<div class="description">
<p>Creates the <a href="Poco.NotificationQueue.html" title="class Poco::NotificationQueue">NotificationQueue</a>. </p>
</div>
<h2>Destructor</h2>
<h3><a name="8808">~NotificationQueue</a></h3>
<p class="decl">~<a href="Poco.NotificationQueue.html" title="class Poco::NotificationQueue">NotificationQueue</a>();</p>
<div class="description">
<p>Destroys the <a href="Poco.NotificationQueue.html" title="class Poco::NotificationQueue">NotificationQueue</a>. </p>
</div>
<h2>Member Functions</h2>
<h3><a name="8822">clear</a></h3>
<p class="decl">void clear();</p>
<div class="description">
<p>Removes all notifications from the queue. </p>
</div>
<h3><a name="8824">defaultQueue</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">static <a href="Poco.NotificationQueue.html" title="class Poco::NotificationQueue">NotificationQueue</a> & defaultQueue();</p>
<div class="description">
<p>Returns a reference to the default <a href="Poco.NotificationQueue.html" title="class Poco::NotificationQueue">NotificationQueue</a>. </p>
</div>
<h3><a name="8813">dequeueNotification</a></h3>
<p class="decl"><a href="Poco.Notification.html" title="class Poco::Notification">Notification</a> * dequeueNotification();</p>
<div class="description">
<p>Dequeues the next pending notification. 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. </p>
<p>It is highly recommended that the result is immediately assigned to a <a href="Poco.Notification.html#8786" title="Poco::Notification::Ptr">Notification::Ptr</a>, to avoid potential memory management issues. </p>
</div>
<h3><a name="8817">dispatch</a></h3>
<p class="decl">void dispatch(<br /> <a href="Poco.NotificationCenter.html" title="class Poco::NotificationCenter">NotificationCenter</a> & notificationCenter<br />);</p>
<div class="description">
<p>Dispatches all queued notifications to the given notification center. </p>
</div>
<h3><a name="8820">empty</a></h3>
<p class="decl">bool empty() const;</p>
<div class="description">
<p>Returns true if and only if the queue is empty. </p>
</div>
<h3><a name="8809">enqueueNotification</a></h3>
<p class="decl">void enqueueNotification(<br /> <a href="Poco.Notification.html#8786" title="Poco::Notification::Ptr">Notification::Ptr</a> pNotification<br />);</p>
<div class="description">
<p>Enqueues the given notification by adding it to the end of the queue (FIFO). The queue takes ownership of the notification, thus a call like </p>
<pre>notificationQueue.enqueueNotification(new MyNotification);
</pre>
<p>does not result in a memory leak. </p>
</div>
<h3><a name="8811">enqueueUrgentNotification</a></h3>
<p class="decl">void enqueueUrgentNotification(<br /> <a href="Poco.Notification.html#8786" title="Poco::Notification::Ptr">Notification::Ptr</a> pNotification<br />);</p>
<div class="description">
<p>Enqueues the given notification by adding it to the front of the queue (LIFO). The event therefore gets processed before all other events already in the queue. The queue takes ownership of the notification, thus a call like </p>
<pre>notificationQueue.enqueueUrgentNotification(new MyNotification);
</pre>
<p>does not result in a memory leak. </p>
</div>
<h3><a name="8823">hasIdleThreads</a></h3>
<p class="decl">bool hasIdleThreads() const;</p>
<div class="description">
<p>Returns true if the queue has at least one thread waiting for a notification. </p>
</div>
<h3><a name="8821">size</a></h3>
<p class="decl">int size() const;</p>
<div class="description">
<p>Returns the number of notifications in the queue. </p>
</div>
<h3><a name="8814">waitDequeueNotification</a></h3>
<p class="decl"><a href="Poco.Notification.html" title="class Poco::Notification">Notification</a> * waitDequeueNotification();</p>
<div class="description">
<p>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. </p>
<p>It is highly recommended that the result is immediately assigned to a <a href="Poco.Notification.html#8786" title="Poco::Notification::Ptr">Notification::Ptr</a>, to avoid potential memory management issues. </p>
</div>
<h3><a name="8815">waitDequeueNotification</a></h3>
<p class="decl"><a href="Poco.Notification.html" title="class Poco::Notification">Notification</a> * waitDequeueNotification(<br /> long milliseconds<br />);</p>
<div class="description">
<p>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. </p>
<p>It is highly recommended that the result is immediately assigned to a <a href="Poco.Notification.html#8786" title="Poco::Notification::Ptr">Notification::Ptr</a>, to avoid potential memory management issues. </p>
</div>
<h3><a name="8819">wakeUpAll</a></h3>
<p class="decl">void wakeUpAll();</p>
<div class="description">
<p>Wakes up all threads that wait for a notification. </p>
</div>
<h3><a name="8825">dequeueOne</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl"><a href="Poco.Notification.html#8786" title="Poco::Notification::Ptr">Notification::Ptr</a> dequeueOne();</p>
<div class="description">
<p></p>
</div>
<p class="footer">POCO C++ Libraries 1.3.6-all<br />
Copyright © 2009, <a href="http://pocoproject.org/" target="_blank">Applied Informatics Software Engineering GmbH and Contributors</a></p>
</div>
</body>
</html>
|
