MIRA
AbstractChannel.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2012 by
3  * MetraLabs GmbH (MLAB), GERMANY
4  * and
5  * Neuroinformatics and Cognitive Robotics Labs (NICR) at TU Ilmenau, GERMANY
6  * All rights reserved.
7  *
8  * Contact: info@mira-project.org
9  *
10  * Commercial Usage:
11  * Licensees holding valid commercial licenses may use this file in
12  * accordance with the commercial license agreement provided with the
13  * software or, alternatively, in accordance with the terms contained in
14  * a written agreement between you and MLAB or NICR.
15  *
16  * GNU General Public License Usage:
17  * Alternatively, this file may be used under the terms of the GNU
18  * General Public License version 3.0 as published by the Free Software
19  * Foundation and appearing in the file LICENSE.GPL3 included in the
20  * packaging of this file. Please review the following information to
21  * ensure the GNU General Public License version 3.0 requirements will be
22  * met: http://www.gnu.org/copyleft/gpl.html.
23  * Alternatively you may (at your option) use any later version of the GNU
24  * General Public License if such license has been publicly approved by
25  * MLAB and NICR (or its successors, if any).
26  *
27  * IN NO EVENT SHALL "MLAB" OR "NICR" BE LIABLE TO ANY PARTY FOR DIRECT,
28  * INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
29  * THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF "MLAB" OR
30  * "NICR" HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  *
32  * "MLAB" AND "NICR" SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
33  * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
34  * FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
35  * ON AN "AS IS" BASIS, AND "MLAB" AND "NICR" HAVE NO OBLIGATION TO
36  * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS OR MODIFICATIONS.
37  */
38 
47 #ifndef _MIRA_ABSTRACTCHANNEL_H_
48 #define _MIRA_ABSTRACTCHANNEL_H_
49 
50 #ifndef Q_MOC_RUN
51 #include <boost/thread/mutex.hpp>
52 #endif
53 
54 #include <error/Exceptions.h>
55 
57 #include <fw/ChannelBuffer.h>
58 
59 namespace mira {
60 
62 
70 class MIRA_FRAMEWORK_EXPORT AbstractChannel : boost::noncopyable
71 {
72 public:
73 
75 
76 public:
77 
79  AbstractChannel(const std::string& id, ChannelBufferBase* buffer);
80 
82  ~AbstractChannel();
83 
84 public:
85 
89  const std::string& getID() const { return mID; }
90 
91 public:
92 
99  int getTypeId() const { return mBuffer->getTypeId(); }
100 
107  Typename getTypename() const { return mBuffer->getTypename(); }
108 
117  void setTypename(const Typename& name) { mBuffer->setTypename(name); }
118 
123  TypeMetaPtr getTypeMeta() const { return mBuffer->getTypeMeta(); }
124 
129  void setTypeMeta(TypeMetaPtr meta) { mBuffer->setTypeMeta(meta); }
130 
138  void fixateType() { mBuffer->fixateType(); }
139 
143  bool isTyped() const { return mBuffer->isTyped(); }
144 
149  ChannelBufferBase* getBuffer() { return mBuffer; }
150 
154  std::size_t getNrOfSlots() const { return mBuffer->getSize(); }
155 
160  Time getLastSlotTime() const { return mLastSlotTime; }
161 
165  uint64 getNrOfDataChanges() const { return mNrOfDataChanges; }
166 
167 public:
168 
172  bool hasSubscriber() const {
173  return !mSubscribers.empty() || mNrOfSubscribersWithoutChannelSubscriber > 0;
174  }
175 
176 
180  bool hasPublisher() const;
181 
189  void removeSubscriber(AbstractChannelSubscriberPtr subscriber);
190 
191 public:
192 
197  void finishWrite(Slot* s);
198 
203  void discardWrite(Slot* s);
204 
205 public:
206 
210  template<typename TargetType>
211  void promote()
212  {
213  boost::mutex::scoped_lock lock(mPromoteMutex);
214  ChannelBufferBase* oldBuffer = mBuffer;
215 
216  // promote our buffer, this may create a new buffer if necessary
217  // then we set the new buffer and destroy the old one afterwards
218  ChannelBufferBase* newBuffer;
219  try {
220  newBuffer = mBuffer->promote<TargetType>();
221  }
222  catch(Exception& ex) {
223  MIRA_RETHROW(ex, "while trying to promote channel '" << this->getID() << "'")
224  }
225 
226  if(newBuffer!=oldBuffer) {
227  // TODO: the next assignment is atomic, hence there should be no
228  // threading problem, even if someone obtains a ChannelRead or
229  // ChannelWrite within the next line. (using a mutex here and in the
230  // read() and write() methods would be even safer, but would also add
231  // some more overhead.)
232  mBuffer = newBuffer; // assign the new buffer
233 
234  // do not delete the old buffer here, as there might be
235  // someone who still holds a lock to a slot. Instead, the buffer
236  // will be freed when this AbstractChannel is destructed.
237  // An alternative would be to use a shared_ptr for mBuffer and
238  // to pass it to the ChannelReadWrite objects.
239  mUntypedBuffer = oldBuffer;
240  }
241  }
242 
243 public:
244 
248  void dbgDump(bool brief=true) { mBuffer->dbgDump(mID, brief); }
249 
250 protected:
251 
252  std::string mID;
255 
256  boost::mutex mPromoteMutex;
257  boost::mutex mSubscribersMutex;
258  std::list<AbstractChannelSubscriberPtr > mSubscribers;
259  uint32 mNrOfSubscribersWithoutChannelSubscriber; // number of subscribers that are subscribed without callback
262 };
263 
266 
268 
270 
271 template<typename TargetType>
272 inline void promote_channel(AbstractChannelPtr channel)
273 {
274  channel->promote<TargetType>();
275 }
276 
277 template<>
278 inline void promote_channel<void>(AbstractChannelPtr channel)
279 {
280  // Do nothing if target type is void (untyped channel).
281  // We can only promote to non-void typed channels.
282 }
283 
285 
287 
288 }
289 
290 #endif
Classes for managing a channels internal buffer (slots).
bool hasSubscriber() const
Returns true, if this channel has at least one subscriber.
Definition: AbstractChannel.h:172
uint64 getNrOfDataChanges() const
Returns the number of times data was written to this channel.
Definition: AbstractChannel.h:165
Base class for all channel subscribers.
specialize cv::DataType for our ImgPixel and inherit from cv::DataType<Vec>
Definition: IOService.h:67
std::string Typename
Definition: Typename.h:60
uint64 mNrOfDataChanges
Definition: AbstractChannel.h:261
AbstractChannel * AbstractChannelPtr
Typedef for abstract channel pointers.
Definition: AbstractChannel.h:265
#define MIRA_RETHROW(ex, msg)
Macro for rethrowing an exception with file and line information and for adding additional informatio...
Definition: Exception.h:144
ChannelBufferBase * promote()
Promotes this buffer to the specified target type (if required).
Definition: ChannelBuffer.h:1187
std::list< AbstractChannelSubscriberPtr > mSubscribers
Definition: AbstractChannel.h:258
int getTypeId() const
Returns the non-portable typeid of the items that are stored in the slots of the underlying channel b...
Definition: AbstractChannel.h:99
void fixateType()
Calling this method will fix the type of the underlying ChannelBuffer.
Definition: AbstractChannel.h:138
Wrapper class for boost::posix_time::ptime for adding more functionality to it.
Definition: Time.h:421
void setTypeMeta(TypeMetaPtr meta)
Sets the type meta information for the slots of the underlying channel buffer.
Definition: AbstractChannel.h:129
std::string mID
Definition: AbstractChannel.h:252
Commonly used exception classes.
ChannelBufferBase::Slot Slot
Definition: AbstractChannel.h:74
#define MIRA_FRAMEWORK_EXPORT
Definition: FrameworkExports.h:61
Definition: AbstractChannel.h:70
ChannelBufferBase * mUntypedBuffer
Definition: AbstractChannel.h:254
boost::mutex mPromoteMutex
Definition: AbstractChannel.h:256
const std::string & getID() const
Returns the channel id of this channel.
Definition: AbstractChannel.h:89
ChannelBufferBase * mBuffer
Definition: AbstractChannel.h:253
boost::shared_ptr< TypeMeta > TypeMetaPtr
Definition: MetaSerializer.h:309
Base class for exceptions.
Definition: Exception.h:194
Base class that manages the slots of channels by providing read and write access to them...
Definition: ChannelBuffer.h:133
Container for storing a single data element in the linked list.
Definition: ChannelBuffer.h:165
Time getLastSlotTime() const
Returns the timestamp of the data in the slot that was last written to this channel or an invalid tim...
Definition: AbstractChannel.h:160
TypeMetaPtr getTypeMeta() const
Returns the type meta information for the slots of the underlying channel buffer. ...
Definition: AbstractChannel.h:123
uint32 mNrOfSubscribersWithoutChannelSubscriber
Definition: AbstractChannel.h:259
void dbgDump(bool brief=true)
Output the current buffer to console for debugging.
Definition: AbstractChannel.h:248
ChannelBufferBase * getBuffer()
Returns the underlying channel buffer.
Definition: AbstractChannel.h:149
Time mLastSlotTime
Definition: AbstractChannel.h:260
Typename getTypename() const
Returns the platform independent typename of the items that are stored in the slots of the underlying...
Definition: AbstractChannel.h:107
boost::shared_ptr< AbstractChannelSubscriber > AbstractChannelSubscriberPtr
Definition: AbstractChannelSubscriber.h:120
bool isTyped() const
Returns true, if the channel is typed and false, if it is untyped.
Definition: AbstractChannel.h:143
void setTypename(const Typename &name)
Sets the typename of the items that are stored in the slots of the underlying channel buffer...
Definition: AbstractChannel.h:117
std::size_t getNrOfSlots() const
Returns the number of slots this channel contains.
Definition: AbstractChannel.h:154
void promote()
Promote the channel to TargetType.
Definition: AbstractChannel.h:211
boost::mutex mSubscribersMutex
Definition: AbstractChannel.h:257