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
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
<!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::AbstractEvent</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="template">template < class TArgs, class TStrategy, class TDelegate ></h1>
<h1 class="symbol">class AbstractEvent</h1>
</div>
<div class="body">
<p>
<b>Library:</b> Foundation<br />
<b>Package:</b> Events<br />
<b>Header:</b> Poco/AbstractEvent.h</p>
<h2>Description</h2>
<div class="description">
<p>An <a href="Poco.AbstractEvent.html" title="class Poco::AbstractEvent">AbstractEvent</a> is the super-class of all events. It works similar to the way C# handles notifications (aka events in C#). Events can be used to send information to a set of observers which are registered at the event. The type of the data is specified with the template parameter TArgs. The TStrategy parameter must be a subclass of <a href="Poco.NotificationStrategy.html" title="class Poco::NotificationStrategy">NotificationStrategy</a>. The parameter TDelegate can either be a subclass of <a href="Poco.AbstractDelegate.html" title="class Poco::AbstractDelegate">AbstractDelegate</a> or of PriorityAbstractDelegate. </p>
<p>Note that <a href="Poco.AbstractEvent.html" title="class Poco::AbstractEvent">AbstractEvent</a> should never be used directly. One ought to use one of its subclasses which set the TStrategy and TDelegate template parameters to fixed values. For most use-cases the <a href="Poco.BasicEvent.html" title="class Poco::BasicEvent">BasicEvent</a> template will be sufficient: </p>
<pre>#include "Poco/BasicEvent.h"
#include "Poco/Delegate.h"
</pre>
<p>If one requires delegates to be called in the order they registered, use <a href="Poco.FIFOEvent.html" title="class Poco::FIFOEvent">FIFOEvent</a>: </p>
<pre>#include "Poco/FIFOEvent.h"
#include "Poco/Delegate.h"
</pre>
<p>Both <a href="Poco.FIFOEvent.html" title="class Poco::FIFOEvent">FIFOEvent</a> and <a href="Poco.BasicEvent.html" title="class Poco::BasicEvent">BasicEvent</a> work with a standard delegate. They allow one object to register exactly one delegate at an event. In contrast, a <a href="Poco.PriorityDelegate.html" title="class Poco::PriorityDelegate">PriorityDelegate</a> comes with an attached priority value and allows one object to register for one priority value one delegate. Note that PriorityDelegates only work with PriorityEvents: </p>
<pre>#include "Poco/PriorityEvent.h"
#include "Poco/PriorityDelegate.h"
</pre>
<p>Use events by adding them as public members to the object which is throwing notifications: </p>
<p></p>
<pre>class MyData
{
public:
Poco::BasicEvent<int> AgeChanged;
MyData();
...
};
</pre>
<p>Throwing the event can be done either by the events <a href="Poco.AbstractEvent.html#3269" title="Poco::AbstractEvent::notify()">notify</a>() or <a href="Poco.AbstractEvent.html#3272" title="Poco::AbstractEvent::notifyAsync()">notifyAsync</a>() method: </p>
<p></p>
<p>Alternatively, instead of <a href="Poco.AbstractEvent.html#3269" title="Poco::AbstractEvent::notify()">notify</a>(), operator () can be used. </p>
<p></p>
<pre>void MyData::setAge(int i)
{
this->_age = i;
AgeChanged(this, this->_age);
}
</pre>
<p>Note that notify and notifyAsync do not catch exceptions, i.e. in case a delegate throws an exception, the notify is immediately aborted and the exception is thrown back to the caller. </p>
<p>Delegates can register methods at the event. In the case of a <a href="Poco.BasicEvent.html" title="class Poco::BasicEvent">BasicEvent</a> or <a href="Poco.FIFOEvent.html" title="class Poco::FIFOEvent">FIFOEvent</a> the <a href="Poco.Delegate.html" title="class Poco::Delegate">Delegate</a> template is used, in case of an <a href="Poco.PriorityEvent.html" title="class Poco::PriorityEvent">PriorityEvent</a> a <a href="Poco.PriorityDelegate.html" title="class Poco::PriorityDelegate">PriorityDelegate</a> is used. Mixing of observers, e.g. using a <a href="Poco.PriorityDelegate.html" title="class Poco::PriorityDelegate">PriorityDelegate</a> with a <a href="Poco.BasicEvent.html" title="class Poco::BasicEvent">BasicEvent</a> is not possible and checked for during compile time. Events require the observers to follow one of the following method signature: </p>
<p></p>
<pre>void onEvent(const void* pSender, TArgs& args);
void onEvent(TArgs& args);
static void onEvent(const void* pSender, TArgs& args);
static void onEvent(void* pSender, TArgs& args);
static void onEvent(TArgs& args);
</pre>
<p>For performance reasons arguments are always sent by reference. This also allows observers to modify the sent argument. To prevent that, use <const TArg> as template parameter. A non-conformant method signature leads to compile errors. </p>
<p>Assuming that the observer meets the method signature requirement, it can register this method with the += operator: </p>
<p></p>
<pre>class MyController
{
protected:
MyData _data;
void onDataChanged(void* pSender, int& data);
...
};
MyController::MyController()
{
_data.AgeChanged += delegate(this, &MyController::onDataChanged);
}
</pre>
<p>In some cases it might be desirable to work with automatically expiring registrations. Simply add to delegate as 3rd parameter a expireValue (in milliseconds): </p>
<p></p>
<pre>_data.DataChanged += delegate(this, &MyController::onDataChanged, 1000);
</pre>
<p>This will add a delegate to the event which will automatically be removed in 1000 millisecs. </p>
<p>Unregistering happens via the -= operator. Forgetting to unregister a method will lead to segmentation faults later, when one tries to send a notify to a no longer existing object. </p>
<p></p>
<pre>MyController::~MyController()
{
_data.DataChanged -= delegate(this, &MyController::onDataChanged);
}
</pre>
<p>Working with PriorityDelegates as similar to working with <a href="Poco.BasicEvent.html" title="class Poco::BasicEvent">BasicEvent</a>/<a href="Poco.FIFOEvent.html" title="class Poco::FIFOEvent">FIFOEvent</a>.Instead of ''delegate'' simply use ''priorityDelegate''. </p>
<p>For further examples refer to the event testsuites. </p>
</div>
<h2>Member Summary</h2>
<p><b>Member Functions: </b><a href="Poco.AbstractEvent.html#3278" title="Poco::AbstractEvent::clear()">clear</a>, <a href="Poco.AbstractEvent.html#3276" title="Poco::AbstractEvent::disable()">disable</a>, <a href="Poco.AbstractEvent.html#3275" title="Poco::AbstractEvent::enable()">enable</a>, <a href="Poco.AbstractEvent.html#3288" title="Poco::AbstractEvent::executeAsyncImpl()">executeAsyncImpl</a>, <a href="Poco.AbstractEvent.html#3277" title="Poco::AbstractEvent::isEnabled()">isEnabled</a>, <a href="Poco.AbstractEvent.html#3269" title="Poco::AbstractEvent::notify()">notify</a>, <a href="Poco.AbstractEvent.html#3272" title="Poco::AbstractEvent::notifyAsync()">notifyAsync</a>, <a href="Poco.AbstractEvent.html#3266" title="Poco::AbstractEvent::operator()">operator</a>, <a href="Poco.AbstractEvent.html#3262" title="Poco::AbstractEvent::operator +=()">operator +=</a>, <a href="Poco.AbstractEvent.html#3264" title="Poco::AbstractEvent::operator -=()">operator -=</a></p>
<h2>Nested Classes</h2>
<h3><a href="Poco.AbstractEvent.NotifyAsyncParams.html" class="class">struct NotifyAsyncParams</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> </h3>
<p> <a href="Poco.AbstractEvent.NotifyAsyncParams.html"><img src="images/arrow.gif" alt="more..." style="vertical-align:baseline;" border="0" /> </a></p>
<h2>Constructors</h2>
<h3><a name="3258">AbstractEvent</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl"><a href="Poco.AbstractEvent.html" title="class Poco::AbstractEvent">AbstractEvent</a>();</p>
<div class="description">
<p></p>
</div>
<h3><a name="3259">AbstractEvent</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl"><a href="Poco.AbstractEvent.html" title="class Poco::AbstractEvent">AbstractEvent</a>(<br /> const TStrategy & strat<br />);</p>
<div class="description">
<p></p>
</div>
<h2>Destructor</h2>
<h3><a name="3261">~AbstractEvent</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">virtual ~<a href="Poco.AbstractEvent.html" title="class Poco::AbstractEvent">AbstractEvent</a>();</p>
<div class="description">
<p></p>
</div>
<h2>Member Functions</h2>
<h3><a name="3278">clear</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void clear();</p>
<div class="description">
<p>Removes all delegates. </p>
</div>
<h3><a name="3276">disable</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void disable();</p>
<div class="description">
<p>Disables the event. notify and notifyAsnyc will be ignored, but adding/removing delegates is still allowed. </p>
</div>
<h3><a name="3275">enable</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void enable();</p>
<div class="description">
<p>Enables the event </p>
</div>
<h3><a name="3277">isEnabled</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">bool isEnabled() const;</p>
<div class="description">
<p></p>
</div>
<h3><a name="3269">notify</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void notify(<br /> const void * pSender,<br /> TArgs & args<br />);</p>
<div class="description">
<p>Sends a notification to all registered delegates. The order is determined by the TStrategy. This method is blocking. While executing, other objects can change the list of delegates. These changes don't influence the current active notifications but are activated with the next notify. If one of the delegates throws an exception, the notify method is immediately aborted and the exception is reported to the caller. </p>
</div>
<h3><a name="3272">notifyAsync</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl"><a href="Poco.ActiveResult.html" title="class Poco::ActiveResult">ActiveResult</a> < TArgs > notifyAsync(<br /> const void * pSender,<br /> const TArgs & args<br />);</p>
<div class="description">
<p>Sends a notification to all registered delegates. The order is determined by the TStrategy. This method is not blocking and will immediately return. The delegates are invoked in a seperate thread. Call activeResult.wait() to wait until the notification has ended. While executing, other objects can change the delegate list. These changes don't influence the current active notifications but are activated with the next notify. If one of the delegates throws an exception, the execution is aborted and the exception is reported to the caller. </p>
</div>
<h3><a name="3266">operator</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void operator () (<br /> const void * pSender,<br /> TArgs & args<br />);</p>
<div class="description">
<p></p>
</div>
<h3><a name="3262">operator +=</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void operator += (<br /> const TDelegate & aDelegate<br />);</p>
<div class="description">
<p>Adds a delegate to the event. If the observer is equal to an already existing one (determined by the < operator), it will simply replace the existing observer. This behavior is determined by the TStrategy. Current implementations (<a href="Poco.DefaultStrategy.html" title="class Poco::DefaultStrategy">DefaultStrategy</a>, <a href="Poco.FIFOStrategy.html" title="class Poco::FIFOStrategy">FIFOStrategy</a>) follow that guideline but future ones can deviate. </p>
</div>
<h3><a name="3264">operator -=</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void operator -= (<br /> const TDelegate & aDelegate<br />);</p>
<div class="description">
<p>Removes a delegate from the event. If the delegate is equal to an already existing one is determined by the < operator. If the observer is not found, the unregister will be ignored </p>
</div>
<h3><a name="3288">executeAsyncImpl</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">TArgs executeAsyncImpl(<br /> const <a href="Poco.AbstractEvent.NotifyAsyncParams.html" title="struct Poco::AbstractEvent::NotifyAsyncParams">NotifyAsyncParams</a> & par<br />);</p>
<div class="description">
<p></p>
</div>
<h2>Variables</h2>
<h3><a name="3291">_enabled</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">bool _enabled;</p>
<div class="description">
<p>Stores if an event is enabled. Notfies on disabled events have no effect but it is possible to change the observers. </p>
</div>
<h3><a name="3287">_executeAsync</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl"><a href="Poco.ActiveMethod.html" title="class Poco::ActiveMethod">ActiveMethod</a> < TArgs, <a href="Poco.AbstractEvent.NotifyAsyncParams.html" title="struct Poco::AbstractEvent::NotifyAsyncParams">NotifyAsyncParams</a>, <a href="Poco.AbstractEvent.html" title="class Poco::AbstractEvent">AbstractEvent</a> > _executeAsync;</p>
<div class="description">
<p></p>
</div>
<h3><a name="3292">_mutex</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">mutable <a href="Poco.FastMutex.html" title="class Poco::FastMutex">FastMutex</a> _mutex;</p>
<div class="description">
<p></p>
</div>
<h3><a name="3290">_strategy</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">TStrategy _strategy;</p>
<div class="description">
<p>The strategy used to notify observers. </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>
|
