minor fixes for clang++
[senf.git] / senf / PPI / MultiConnectorMixin.hh
1 // $Id$
2 //
3 // Copyright (C) 2009
4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 //
6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
7 // Version 1.0 (the "License"); you may not use this file except in compliance
8 // with the License. You may obtain a copy of the License at 
9 // http://senf.berlios.de/license.html
10 //
11 // The Fraunhofer FOKUS Public License Version 1.0 is based on, 
12 // but modifies the Mozilla Public License Version 1.1.
13 // See the full license text for the amendments.
14 //
15 // Software distributed under the License is distributed on an "AS IS" basis, 
16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License 
17 // for the specific language governing rights and limitations under the License.
18 //
19 // The Original Code is Fraunhofer FOKUS code.
20 //
21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V. 
22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
23 // All Rights Reserved.
24 //
25 // Contributor(s):
26 //   Stefan Bund <g0dil@berlios.de>
27
28 /** \file
29     \brief MultiConnectorMixin public header */
30
31 #ifndef HH_SENF_PPI_MultiConnectorMixin_
32 #define HH_SENF_PPI_MultiConnectorMixin_ 1
33
34 // Custom includes
35 #include <senf/config.hh>
36 #include <boost/ptr_container/ptr_map.hpp>
37 #include <boost/ptr_container/ptr_vector.hpp>
38 #include <boost/mpl/if.hpp>
39
40 #ifndef SENF_MULTI_CONNECTOR_MAX_ARGS
41 #define SENF_MULTI_CONNECTOR_MAX_ARGS 3
42 #endif
43
44 #include "MultiConnectorMixin.mpp"
45 #include "MultiConnectorMixin.ih"
46 //-/////////////////////////////////////////////////////////////////////////////////////////////////
47
48 namespace senf {
49 namespace ppi {
50
51 #ifdef DOXYGEN
52
53     // For exposition only.
54     // Other implementations with 0..SENF_MULTI_CONNECTOR_MAX_ARGS arguments accordingly
55     // The real implementation includes a boost::enable_if condition in the return value, which is
56     // used to only enable the correct overload: The first overload, if the MultiConnector is an
57     // output, otherwise the second overload.
58
59     /** \brief Connect MultiConnector source to arbitrary target
60
61         Additional implementations with 0..SENF_MULTI_CONNECTOR_MAX_ARGS arguments.
62
63         \related module::MultiConnectorMixin
64      */
65     template <class MultiConnectorSource, class Target, class A1>
66     MultiConnectorSource::ConnectorType & connect(
67         MultiConnectorSource & source, A1 const & a1, Target & target);
68
69     /** \brief Connect arbitrary source to MultiConnector target
70
71         Additional implementations with 0..SENF_MULTI_CONNECTOR_MAX_ARGS arguments.
72
73         \related module::MultiConnectorMixin
74      */
75     template <class Source, class MultiConnectorTarget, class A1>
76     MultiConnectorTarget::ConnectorType & connect(
77         Source & source, MultiConnectorTarget & target, A1 const & a1);
78
79     template <class MultiConnectorSource, class MultiConnectorTarget, class A1, class A2>
80     std::pair<MultiConnectorSource::ConnectorType &, MultiConnectorTarget::ConnectorType &>
81     connect(
82         MultiConnectorSource & source, MultiConnectorTarget & target, A1 const & a1, A2 const & a2);
83
84 #else
85
86     // Include 'senf::ppi namespace member declarations' from MultiConnectorMixin.mpp
87 #   define BOOST_PP_ITERATION_PARAMS_1 (4, ( \
88             0, \
89             SENF_MULTI_CONNECTOR_MAX_ARGS, \
90             SENF_ABSOLUTE_INCLUDE_PATH(PPI/MultiConnectorMixin.mpp), \
91             2 ))
92 #   include BOOST_PP_ITERATE()
93
94 #endif
95
96 namespace module {
97
98     namespace detail { struct MultiConnectorMixinAccess; }
99
100     /** \brief Multi-Connector management
101
102         This mixin provides a module with support for a runtime configurable number of input or
103         output connectors.
104         \code
105         class MyModule
106             : public senf::ppi::module::Module,
107               public senf::ppi::module::MultiConnectorMixin<
108                   MyModule, senf::ppi::connector::ActiveInput<> >
109         {
110             SENF_PPI_MODULE(MyModule);
111         public:
112             senf::ppi::connector::PassiveOutput<> output;
113
114             // ...
115
116         private:
117             void connectorSetup(senf::ppi::connector::ActiveInput & input)
118             {
119                 route(input, output);
120                 input.onThrottle(&MyModule::doThrottle);
121             }
122
123             // Optional
124             void connectorDestroy(senf::ppi::connector::ActiveInput const & input)
125             {
126                  //  whatever
127             }
128
129             void doThrottle()
130             {
131                 // ...
132             }
133
134             friend class senf::ppi::module::MultiConnectorMixin<
135                 MyModule, senf::ppi::connector::ActiveInput<> >;
136         }
137         \endcode
138
139         Using the MultiConnectorMixin consists of
140         \li inheriting from MultiConnectorMixin
141         \li defining a function \c connectorSetup
142         \li declaring the mixin as a friend
143         \li optionally defining \c connectorDestroy to be notified when connectors are disconnected
144
145         The MultiConnectorMixin takes several template arguments
146         \li the name of the derived class, \a Self_
147         \li the type of connector, \a ConnectorType_
148         \li an optional \a KeyType_ if a mapping container is required
149         \li an optional \a ContainerType_ to replace the default \c boost::ptr_vector or \c
150             boost::ptr_map.
151
152         \section senf_ppi_multiconnector_sequence Sequence/vector based multi connector mixin
153
154         If no \a KeyType_ is given (or the \a KeyType_ is \c void), the mixin will use a sequence
155         container, by default a \c boost::ptr_vector to store the connectors. In this case, new
156         connectors will be added to the end of the container. The \c connectorSetup() routine
157         however may be used to move the inserted connector to some other location, e.g.
158         \code
159         container().insert(begin(), container().pop_back().release());
160         \endcode
161         which will move the new connector from the end to the beginning. If you want to abort adding
162         the new connector, you may throw an exception.
163
164         \par "Example:" senf::ppi::module::PriorityJoin
165
166         \section senf_ppi_multiconnector_map Map based multi connector mixin
167
168         If \a KeyType_ is given (and is not \c void), the mixin will use a mapping container, by
169         default a \c boost::ptr_map to store the connectors. The \c connectorSetup() member function
170         must return the key value under which the new connector will be stored. The new connector
171         will this be written to the container only \e after \c connectorSetup() returns.
172
173         When the returned key is not unique, the new connector will \e replace the old one. If this
174         is not what you want, either check for an already existing member and throw an exception in
175         \c connectorSetup() or replace the \c boost::ptr_map by a \c boost::ptr_multimap using the
176         fourth template argument to MultiConnectorMixin.
177
178         \par "Example:" senf::ppi::module::AnnotationRouter
179
180         \section senf_ppi_multiconnector_connect Connect and additional connectorSetup() arguments
181
182         When connecting to a module using the MultiConnectorMixin, every new connect call will
183         allocate a new connector
184         \code
185         MyModule muModule;
186
187         senf::ppi::connect(someModule, myModule);
188         \endcode
189         Some modules will expect additional arguments to be passed (see below)
190         \code
191         MyModule myModule;
192
193         senf::ppi::connect(mod1, myModule);     // index = 0, see below
194         senf::ppi::connect(mod2, myModule, 1);  // index = 1, see below
195         \endcode
196         To declare these additional arguments, just declare \c connectorSetup() with those
197         additional arguments:
198         \code
199         void connectorSetup(MyModule::ConnectorType & input, int index=0)
200         {
201             container().insert(container().begin()+index, container().pop_back().release());
202         }
203         \endcode
204
205         \par "Advanced note:" These additional arguments are always passed by const-reference. If
206             you need to pass a non-const reference, declare the \c connectorSetup() argument as
207             non-const reference and wrap the real argument using \c boost::ref() (The reason for
208             this is known as 'The forwarding problem').
209
210         \section senf_ppi_multiconnector_advanced Advanced usage: Managing your own container
211
212         If you need to use a completely different type of container, you can take over the container
213         management yourself. To do this, pass \c void as container type and change \c
214         connectorSetup() to take an \c std::auto_ptr as argument. \c connectorSetup() must ensure to
215         save this connector in some container or throw an exception.
216
217         Implementing \c connectorDestroy now is \e mandatory. The signature is changed to take a
218         pointer as argument
219         \code
220         class MyModule
221             : public senf::ppi::module::Module,
222               public senf::ppi::module::MultiConnectorMixin<
223                   MyModule, senf::ppi::connector::ActiveInput<>, void, void >
224         {
225             SENF_PPI_MODULE(MyModule);
226         public:
227             // ...
228
229         private:
230             void connectorSetup(std::auto_ptr<ConnectorType> conn, unsigned p)
231             {
232                 if (p>connectors_.size())
233                    throw SomeErrorException();
234                 route(*conn, output);
235                 connectors_.insert(connectors_.begin()+p,conn);
236             }
237
238             void connectorDestroy(ConnectorType const * conn)
239             {
240                 using boost::lambda::_1;
241                 boost::ptr_vector<ConnectorType>::iterator i (
242                     std::find_if(connectors_.begin(),connectors_.end(), &_1==conn))
243                 if (i != connectors_.end())
244                     connectors_.erase(i);
245             }
246
247             boost::ptr_vector<ConnectorType> connectors_;
248         };
249         \endcode
250         \warning You must make absolutely sure the connector does not get deleted when returning
251             normally from \c connectorSetup(): The connector \e must be saved somewhere
252             successfully, otherwise your code will break.
253
254      */
255     template <class Self_,
256               class ConnectorType_,
257               class KeyType_=void,
258               class ContainerType_=typename detail::MultiConnectorDefaultContainer<
259                                                KeyType_,ConnectorType_>::type>
260     class MultiConnectorMixin
261         : private detail::MultiConnectorSelectBase<ConnectorType_>::type
262     {
263     public:
264         typedef ConnectorType_ ConnectorType; ///< Type of MultiConnector connector
265
266     protected:
267         typedef ContainerType_ ContainerType; ///< Type of connector container
268
269         ContainerType_ & connectors();        ///< Get connector container
270         ContainerType_ const & connectors() const; ///< Get connectors container (const)
271
272         void connectorDestroy(ConnectorType const &);
273
274     private:
275
276 #ifndef DOXYGEN
277
278         // Include 'MultiConnectorMixin member declaration' from MultiConnectorMixin.mpp
279 #       define BOOST_PP_ITERATION_PARAMS_1 (4, ( \
280             0, \
281             SENF_MULTI_CONNECTOR_MAX_ARGS, \
282             SENF_ABSOLUTE_INCLUDE_PATH(PPI/MultiConnectorMixin.mpp), \
283             1 ))
284 #       include BOOST_PP_ITERATE()
285
286 #endif
287
288         void disconnected(ConnectorType_ const & c);
289
290         friend struct detail::MultiConnectorMixinAccess;
291         friend class detail::MultiConnectorWrapper<Self_,ConnectorType_>;
292
293         ContainerType_ connectors_;
294     };
295
296 #ifndef DOXYGEN
297
298     template <class Self_,
299               class ConnectorType_,
300               class ContainerType_>
301     class MultiConnectorMixin<Self_,ConnectorType_,void,ContainerType_>
302         : private detail::MultiConnectorSelectBase<ConnectorType_>::type
303     {
304     public:
305         typedef ConnectorType_ ConnectorType;
306
307     protected:
308         typedef ContainerType_ ContainerType;
309
310         ContainerType_ & connectors();
311         ContainerType_ const & connectors() const;
312
313         void connectorDestroy(ConnectorType const &);
314
315     private:
316
317         // Include 'MultiConnectorMixin member declaration' from MultiConnectorMixin.mpp
318 #       define BOOST_PP_ITERATION_PARAMS_1 (4, ( \
319             0, \
320             SENF_MULTI_CONNECTOR_MAX_ARGS, \
321             SENF_ABSOLUTE_INCLUDE_PATH(PPI/MultiConnectorMixin.mpp), \
322             1 ))
323 #       include BOOST_PP_ITERATE()
324
325         void disconnected(ConnectorType_ const & c);
326
327         friend struct detail::MultiConnectorMixinAccess;
328         friend class detail::MultiConnectorWrapper<Self_,ConnectorType_>;
329
330         ContainerType_ connectors_;
331     };
332
333     template <class Self_,
334               class ConnectorType_>
335     class MultiConnectorMixin<Self_,ConnectorType_,void,void>
336         : private detail::MultiConnectorSelectBase<ConnectorType_>::type
337     {
338     public:
339         typedef ConnectorType_ ConnectorType;
340
341     private:
342
343         // Include 'MultiConnectorMixin member declaration' from MultiConnectorMixin.mpp
344 #       define BOOST_PP_ITERATION_PARAMS_1 (4, ( \
345             0, \
346             SENF_MULTI_CONNECTOR_MAX_ARGS, \
347             SENF_ABSOLUTE_INCLUDE_PATH(PPI/MultiConnectorMixin.mpp), \
348             1 ))
349 #       include BOOST_PP_ITERATE()
350
351         void disconnected(ConnectorType_ const & c);
352
353         friend struct detail::MultiConnectorMixinAccess;
354         friend class detail::MultiConnectorWrapper<Self_,ConnectorType_>;
355     };
356
357 #endif
358
359 }}}
360
361 //-/////////////////////////////////////////////////////////////////////////////////////////////////
362 //#include "MultiConnectorMixin.cci"
363 #include "MultiConnectorMixin.ct"
364 #include "MultiConnectorMixin.cti"
365 #endif
366
367 \f
368 // Local Variables:
369 // mode: c++
370 // fill-column: 100
371 // comment-column: 40
372 // c-file-style: "senf"
373 // indent-tabs-mode: nil
374 // ispell-local-dictionary: "american"
375 // compile-command: "scons -u test"
376 // End: