bug in RC
[anna.git] / include / anna / comm / ReceiverFactory.hpp
1 // ANNA - Anna is Not Nothingness Anymore                                                         //
2 //                                                                                                //
3 // (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo                         //
4 //                                                                                                //
5 // See project site at http://redmine.teslayout.com/projects/anna-suite                           //
6 // See accompanying file LICENSE or copy at http://www.teslayout.com/projects/public/anna.LICENSE //
7
8
9 #ifndef anna_comm_ReceiverFactory_hpp
10 #define anna_comm_ReceiverFactory_hpp
11
12 #include <anna/core/RuntimeException.hpp>
13 #include <anna/core/mt/Mutex.hpp>
14 #include <anna/config/defines.hpp>
15
16 namespace anna {
17
18 namespace xml {
19 class Node;
20 }
21
22 namespace comm {
23
24 class Receiver;
25
26 /**
27    Interface for receivers factories.
28
29    Is recommended (performance  issues) to use #Recycler<T> as in the following example:
30
31    \code
32
33    class MyReceiver;
34
35    class MyReceiverFactory : public ReceiverFactory {
36    public:
37       MyReceiverFactory () : ReceiverFactory ("MyReceiverFactory") {;}
38
39    private:
40       anna::Recycler<MyReceiver> a_receivers;
41
42       Receiver* do_create () throw () { return a_receivers.create (); }
43       void do_release (Receiver* receiver) throw () { a_receivers.release (static_cast <MyReceiver*> (receiver)); }
44    };
45
46    \endcode
47
48    In most of cases, is recommended to use an comm::ReceiverFactoryImpl instance with the receiver type used in our application.
49
50    \see Receiver
51    \see ReceiverFactoryImpl
52 */
53 class ReceiverFactory : public Mutex {
54 public:
55   /**
56      Returns the logical name for this receiver factory.
57      @return logical name for this receiver factory.
58   */
59   const std::string& getName() const throw() { return a_name; }
60
61   /**
62      Creates a receiver instance for this factory. Reuse resources when needed.
63
64      \return The new receiver instance.
65      \warning All the receivers obtained shall be released by mean #release.
66   */
67   Receiver* create() throw(RuntimeException);
68
69   /**
70      Release the receiver instance provided.
71
72      \return The receiver instance to be released.
73      \warning The parameter should have been obtained by mean #create.
74   */
75   void release(Receiver* receiver) throw();
76
77   /**
78      Returns a string with relevant information for this instance.
79      @return string with relevant information for this instance.
80   */
81   std::string asString() const
82   throw() {
83     std::string msg("anna::comm::ReceiverFactory { Name: ");
84     msg += a_name;
85     return msg += " }";
86   }
87
88   /**
89      Returns a XML document with relevant information for this instance.
90      \param parent XML node from which created data will depend on.
91      @return a XML document with relevant information for this instance.
92   */
93   xml::Node* asXML(xml::Node* parent) const throw();
94
95 protected:
96   /**
97      Constructor.
98      \param name Logical name for this receivers factory.
99   */
100   ReceiverFactory(const char* name);
101
102   /**
103      Creates the receiver instance if no other reusable instance is found. This method is
104      called from a critical section activated for this instance.
105
106      \return The new receiver instance.
107      \warning All the receivers obtained shall be released by mean #release.
108   */
109   virtual Receiver* do_create() throw() = 0;
110
111   /**
112      Release the receiver provided. This method is called from a critical section activated
113      for this instance.
114
115      \param The receiver instance to be released.
116   */
117   virtual void do_release(Receiver* receiver) throw() = 0;
118
119 private:
120   const std::string a_name;
121
122   ReceiverFactory(const ReceiverFactory&);
123
124   WHEN_SINGLETHREAD(Receiver* a_receiver;)
125 };
126
127 }
128 }
129
130 #endif