ACE/examples/Bounded_Packet_Relay/BPR_Drivers.h

   1 /* -*- C++ -*- */
   2
   3 //=============================================================================
   4 /**
   5  *  @file    BPR_Drivers.h
   6  *
   7  *  This code builds abstractions to factor out common code from
   8  *  the different possible implementations of the Timer_Queue based
   9  *  bounded packet relay example.
  10  *
  11  *  @author Chris Gill           <cdgill@cs.wustl.edu>  and Douglas C. Schmidt   <d.schmidt@vanderbilt.edu> Based on the Timer Queue Test example written by Carlos O'Ryan        <coryan@cs.wustl.edu>  and Douglas C. Schmidt   <d.schmidt@vanderbilt.edu> and Sergio Flores-Gaitan <sergio@cs.wustl.edu>
  12  */
  13 //=============================================================================
  14
  15
  16 #ifndef _BPR_DRIVERS_H_
  17 #define _BPR_DRIVERS_H_
  18
  19 #include "ace/Functor.h"
  20
  21 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  22 # pragma once
  23 #endif /* ACE_LACKS_PRAGMA_ONCE */
  24
  25 #include "ace/Reactor.h"
  26 #include "ace/Task.h"
  27
  28 // forward declarations
  29 class Input_Device_Wrapper_Base;
  30 class Output_Device_Wrapper_Base;
  31
  32 /**
  33  * @class Bounded_Packet_Relay
  34  *
  35  * @brief This class defines a packet relay abstraction for a
  36  * transmission bounded external commands to start and end the
  37  * transmission.  The transmission may be bounded by the number
  38  * of packets to send, the dration of the transmission, or any
  39  * other factors.
  40  *
  41  * The relay abstraction implemented by this class registers a
  42  * callback command with an input device wrapper, and relays
  43  * input to an output device at a pace specified in the start
  44  * transmission call.
  45  */
  46 class Bounded_Packet_Relay
  47 {
  48 public:
  49   // = Enumerates possible status values for a transmission.
  50   enum Transmission_Status
  51   {
  52     UN_INITIALIZED,
  53     STARTED,
  54     COMPLETED,
  55     TIMED_OUT,
  56     CANCELLED,
  57     ERROR_DETECTED
  58   };
  59
  60   enum Queue_Defaults
  61   {
  62     DEFAULT_HWM = 0x7FFFFFFF,
  63     DEFAULT_LWM = 0x7FFFFFFF
  64   };
  65
  66   /// Command entry point type definition.
  67   typedef int (Bounded_Packet_Relay::*ACTION) (void *);
  68
  69   /// Constructor.
  70   Bounded_Packet_Relay (ACE_Thread_Manager *input_task_mgr,
  71                         Input_Device_Wrapper_Base *input_wrapper,
  72                         Output_Device_Wrapper_Base *output_wrapper);
  73
  74   /// Destructor.
  75   virtual ~Bounded_Packet_Relay ();
  76
  77   /// Requests output be sent to output device.
  78   int send_input ();
  79
  80   /// Requests a transmission be started.
  81   int start_transmission (u_long packet_count,
  82                           u_long arrival_period,
  83                           int logging_level);
  84
  85   /// Requests a transmission be ended.
  86   int end_transmission (Transmission_Status status);
  87
  88   /// Requests a report of statistics from the last transmission.
  89   int report_statistics ();
  90
  91   // = Command accessible entry points.
  92
  93   /// Public entry point to which to push input.
  94   int receive_input (void *);
  95
  96   // = Accessors and mutators for relay settings
  97
  98   /// Get high water mark for relay queue.
  99   ACE_UINT32 queue_hwm ();
 100
 101   /// Set high water mark for relay queue.
 102   void queue_hwm (ACE_UINT32 hwm);
 103
 104   /// Get low water mark for relay queue.
 105   ACE_UINT32 queue_lwm ();
 106
 107   /// Set low water mark for relay queue.
 108   void queue_lwm (ACE_UINT32 lwm);
 109
 110 private:
 111   // = Concurrency Management.
 112
 113   /// flag for whether or not a transmission is active
 114   int is_active_;
 115
 116   /// Thread manager for the input device task.
 117   ACE_Thread_Manager * input_task_mgr_;
 118
 119   /// Pointer to the input device wrapper.
 120   Input_Device_Wrapper_Base * input_wrapper_;
 121
 122   /// Pointer to the output device wrapper.
 123   Output_Device_Wrapper_Base * output_wrapper_;
 124
 125   /// Queue used to buffer input messages.
 126   ACE_Message_Queue<ACE_SYNCH> queue_;
 127
 128   /// High water mark for relay queue.
 129   ACE_UINT32 queue_hwm_;
 130
 131   /// Low water mark for relay queue.
 132   ACE_UINT32 queue_lwm_;
 133
 134   /// Lock for thread-safe synchronization of transmission startup and
 135   /// termination.
 136   ACE_SYNCH_MUTEX transmission_lock_;
 137
 138   // = Transmission Statistics
 139
 140   /// Returns string corresponding to current status.
 141   const char *status_msg ();
 142
 143   /// Number of transmissions sent.
 144   u_long transmission_number_;
 145
 146   /// Count of packets sent in the most recent transmission.
 147   u_long packets_sent_;
 148
 149   /// Status of the current or most recent transmission.
 150   Transmission_Status status_;
 151
 152   /// Start time of the most recent transmission.
 153   ACE_Time_Value transmission_start_;
 154
 155   /// Ending time of the most recent transmission.
 156   ACE_Time_Value transmission_end_;
 157 };
 158
 159 /**
 160  * @class Input_Device_Wrapper_Base
 161  *
 162  * @brief This class defines an abstract base class for an input device
 163  * wrapper that hides the details of the specific device and
 164  * provides a consistent message passing interface without
 165  * knowing anything about the implementation of the input device
 166  * or the message receiver.
 167  * The abstract base class ctor takes a command template object
 168  * that is instantiated with the correct receiver and action
 169  * types. This command object is used to send newly created input
 170  * messages to the receiver.
 171  * The abstract base class is designed to operate in an active
 172  * "push" mode, sending input data to the receiver whenever the
 173  * data is ready.  The underlying device may be active, notifying
 174  * the wrapper when data is ready, or may be passive in which
 175  * case the wrapper must rely on a reactive and/or polling
 176  * mechanism.
 177  *
 178  * Derived classes are responsible for filling in concrete
 179  * definitions for the abstract message creation method and the
 180  * svc method.
 181  */
 182 class Input_Device_Wrapper_Base : public ACE_Task_Base
 183 {
 184 public:
 185   /// Constructor.
 186   Input_Device_Wrapper_Base (ACE_Thread_Manager *input_task_mgr);
 187
 188   /// Destructor.
 189   virtual ~Input_Device_Wrapper_Base ();
 190
 191   /// Sets send input message command in the input device driver
 192   /// object.
 193   int set_send_input_msg_cmd (ACE_Command_Base *send_input_msg_cmd);
 194
 195   /// Sets period (in usecs) between when inputs are created.
 196   int set_input_period (u_long input_period);
 197
 198   /// Sets count of messages to send.
 199   int set_send_count (long count);
 200
 201   /**
 202    * Requests that the input device stop sending messages and
 203    * terminate its thread.  Should return 1 if it will do so, 0 if it
 204    * has already done so, or -1 if there is a problem doing so.
 205    */
 206   int request_stop ();
 207
 208   /// This method runs the input device loop in the new thread.
 209   virtual int svc ();
 210
 211   /// Provides an abstract interface to allow modifying device
 212   /// settings.
 213   virtual int modify_device_settings (void *) = 0;
 214
 215 protected:
 216   /// Creates a new message block, carrying data read from the
 217   /// underlying input device.
 218   virtual ACE_Message_Block *create_input_message () = 0;
 219
 220   /**
 221    * Sends a newly created message block, carrying data read from the
 222    * underlying input device, by passing a pointer to the message
 223    * block to its command execution.
 224    */
 225   virtual int send_input_message (ACE_Message_Block *);
 226
 227   /// Send newly created input message.
 228   ACE_Command_Base *send_input_msg_cmd_;
 229
 230   /// Period between when input values are produced (usecs).
 231   u_long input_period_;
 232
 233   /// Reactor used to multiplex input streams, timeouts.
 234   ACE_Reactor reactor_;
 235
 236   /// Flag to indicate whether or not input object is
 237   /// (and should remain) active.
 238   int is_active_;
 239
 240   /// Count of messages to send before stopping (-1 indicates the
 241   /// device should not stop).
 242   long send_count_;
 243
 244   /// Currently remaining count of messages to send before stopping
 245   /// (-1 indicates the device should not stop).
 246   long current_count_;
 247 };
 248
 249 /**
 250  * @class Output_Device_Wrapper_Base
 251  *
 252  * @brief This class defines an abstract base class for an output device
 253  * wrapper that hides the details of the specific device and
 254  * provides a consistent write method interface without knowing
 255  * anything about the implementation.
 256  *
 257  * The abstract methods write_output_message () and
 258  * modify_device_settings () are defined in derived classes to
 259  * write the contents of the passed message out the underlying
 260  * output device, and update device settings, respectively.
 261  */
 262 class Output_Device_Wrapper_Base
 263 {
 264 public:
 265   virtual ~Output_Device_Wrapper_Base ();
 266
 267   /// Writes contents of the passed message block out to the underlying
 268   /// output device.
 269   virtual int write_output_message (void *) = 0;
 270
 271   /// Provides an abstract interface to allow modifying device
 272   /// settings.
 273   virtual int modify_device_settings (void *) = 0;
 274 };
 275
 276 // include the templates
 277 #include "BPR_Drivers_T.h"
 278
 279 #endif /* _BPR_DRIVERS_H_ */