TAO/tao/LF_Event.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file LF_Event.h
   6  *
   7  *  @author Carlos O'Ryan <coryan@uci.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef TAO_LF_EVENT_H
  12 #define TAO_LF_EVENT_H
  13
  14 #include /**/ "ace/pre.h"
  15
  16 #include /**/ "tao/TAO_Export.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include /**/ "tao/Versioned_Namespace.h"
  23
  24 TAO_BEGIN_VERSIONED_NAMESPACE_DECL
  25
  26 class TAO_LF_Follower;
  27 class TAO_Leader_Follower;
  28
  29 /**
  30  * @class TAO_LF_Event
  31  *
  32  * @brief Use the Leader/Follower loop to wait for one specific event.
  33  *
  34  * The Leader/Follower event loop is used to wait for incoming
  35  * responses, as well as to wait for all the data to be flushed.
  36  * This class encapsulates this event loop. It uses Template Method to
  37  * parametrize the 'waited for' predicate (i.e. reply received or
  38  * message sent or connection establishment etc.)
  39  *
  40  * @todo Implementing the Leader/Followers loop in this class, as
  41  * well as the callbacks to communicate that an event has completed
  42  * leads to excessive coupling.  A better design would use a separate
  43  * class to signal the events, that would allow us to remove the
  44  * Leader/Followers logic from the ORB.  However, that requires other
  45  * major changes and it somewhat complicates the design.
  46  */
  47 class TAO_Export TAO_LF_Event
  48 {
  49 public:
  50   friend class TAO_Leader_Follower;
  51
  52   /// Constructor
  53   TAO_LF_Event ();
  54
  55   /// Destructor
  56   virtual ~TAO_LF_Event ();
  57
  58   /// Bind a follower
  59   /**
  60    * An event can be waited on by at most one follower thread, this
  61    * method is used to bind the waiting thread to the event, in order
  62    * to let the event signal any important state changes.
  63    *
  64    * This is virtual to allow the LF_Multi_Event derived type share
  65    * the follower with all the subordinate LF_CH_Events.
  66    *
  67    * @return -1 if the LF_Event is already bound, 0 otherwise
  68    */
  69   virtual int bind (TAO_LF_Follower *follower);
  70
  71   /// Unbind the follower
  72   virtual int unbind (TAO_LF_Follower *follower);
  73
  74   //@{
  75   /** @name State management
  76    *
  77    * A Leader/Followers event goes through several states during its
  78    * lifetime. We use an enum to represent those states and state
  79    * changes are validated according to the rules defined in the
  80    * concrete classes. We treat the states as finite states in a
  81    * FSM. The possible sequence of states through which the FSM
  82    * migrates is defined in the concrete classes.
  83    */
  84   enum LFS_STATE {
  85     /// The event is created, and is in initial state
  86     LFS_IDLE = 0,
  87     /// The event is active
  88     LFS_ACTIVE,
  89     /// The event is waiting for connection completion.
  90     LFS_CONNECTION_WAIT,
  91     /// The event has completed successfully
  92     LFS_SUCCESS,
  93     /// A failure has been detected while the event was active
  94     LFS_FAILURE,
  95     /// The event has timed out
  96     LFS_TIMEOUT,
  97     /// The connection was closed.
  98     LFS_CONNECTION_CLOSED
  99   };
 100
 101   /// Accessor to change the state. The state isn't changed unless
 102   /// certain conditions are satisfied.
 103   void state_changed (LFS_STATE new_state, TAO_Leader_Follower &lf);
 104
 105   /// Return true if the condition was satisfied successfully, false if it
 106   /// has not
 107   bool successful (TAO_Leader_Follower &lf) const;
 108
 109   /// Return true if an error was detected while waiting for the
 110   /// event
 111   bool error_detected (TAO_Leader_Follower &lf) const;
 112
 113   /// Check if we should keep waiting.
 114   bool keep_waiting (TAO_Leader_Follower &lf) const;
 115   //@}
 116
 117   /// Reset the state, irrespective of the previous states
 118   void reset_state (LFS_STATE new_state);
 119
 120   static const char *state_name (LFS_STATE st);
 121
 122 protected:
 123   /// Validate the state change
 124   virtual void state_changed_i (LFS_STATE new_state) = 0;
 125
 126   /// Check if we should keep waiting.
 127   bool keep_waiting_i () const;
 128
 129   /// Return true if the condition was satisfied successfully, false if it
 130   /// has not
 131   virtual bool successful_i () const = 0 ;
 132
 133   /// Return true if an error was detected while waiting for the
 134   /// event
 135   virtual bool error_detected_i () const = 0;
 136
 137   /// Check whether we have reached the final state..
 138   virtual bool is_state_final () const = 0;
 139
 140 private:
 141   /// Set the state irrespective of anything.
 142   virtual void set_state (LFS_STATE new_state);
 143
 144 protected:
 145   /// The current state
 146   LFS_STATE state_;
 147
 148   /// The bounded follower
 149   TAO_LF_Follower *follower_;
 150 };
 151
 152 TAO_END_VERSIONED_NAMESPACE_DECL
 153
 154 #if defined (__ACE_INLINE__)
 155 # include "tao/LF_Event.inl"
 156 #endif /* __ACE_INLINE__ */
 157
 158 #include /**/ "ace/post.h"
 159
 160 #endif  /* TAO_LF_EVENT_H */