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