ACE/examples/Bounded_Packet_Relay/Thread_Bounded_Packet_Relay.h

   1 /* -*- C++ -*- */
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Thread_Bounded_Packet_Relay.h
   6  *
   7  *  This code provides a thread based implementation
   8  *  of the bounded packet relay example.
   9  *
  10  *  @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>
  11  */
  12 //=============================================================================
  13
  14
  15 #ifndef _THREAD_BOUNDED_PACKET_RELAY_H_
  16 #define _THREAD_BOUNDED_PACKET_RELAY_H_
  17
  18 #include "ace/Functor_T.h"
  19
  20 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  21 # pragma once
  22 #endif /* ACE_LACKS_PRAGMA_ONCE */
  23
  24 #include "ace/Task.h"
  25 #include "ace/Timer_Heap_T.h"
  26 #include "ace/Timer_Queue_Adapters.h"
  27 #include "ace/Event_Handler_Handle_Timeout_Upcall.h"
  28 #include "BPR_Drivers.h"
  29
  30 // These typedefs ensure that we use the minimal amount of locking
  31 // necessary.
  32 typedef ACE_Event_Handler_Handle_Timeout_Upcall
  33         Upcall;
  34 typedef ACE_Timer_Heap_T<ACE_Event_Handler *,
  35                          Upcall,
  36                          ACE_Null_Mutex>
  37         Timer_Heap;
  38 typedef ACE_Timer_Heap_Iterator_T<ACE_Event_Handler *,
  39                                   Upcall,
  40                                   ACE_Null_Mutex>
  41         Timer_Heap_Iterator;
  42 typedef ACE_Thread_Timer_Queue_Adapter<Timer_Heap>
  43         Thread_Timer_Queue;
  44
  45 // Forward declaration.
  46 class Thread_Bounded_Packet_Relay_Driver;
  47
  48 /**
  49  * @class Text_Input_Device_Wrapper
  50  *
  51  * @brief Defines a wrapper for a simple active looping text input
  52  * pseudo-device.
  53  *
  54  * The wrapper is an active object, running in its own thread,
  55  * and uses a reactor to generate timeouts.  When a timeout
  56  * occurs, the wrapper calls its concrete message creation
  57  * method. The wrapper then calls its base class message send
  58  * method to forward the message to the receiver.
  59  * A more sophisticated version of this class would use the
  60  * reactive capabilities as well as the timeout generating
  61  * capabilities of the reactor, multiplexing several input
  62  * streams.  Comments to this effect appear in the definition of
  63  * the event loop method.
  64  */
  65 class Text_Input_Device_Wrapper : public Input_Device_Wrapper_Base
  66 {
  67 public:
  68   // = Enumerated logging level flags
  69   enum Logging_Flags {NO_LOGGING = 0,
  70                       LOG_MSGS_CREATED = 1};
  71
  72   /// Constructor.
  73   Text_Input_Device_Wrapper (ACE_Thread_Manager *input_task_mgr,
  74                              size_t read_length,
  75                              const char* text,
  76                              int logging = 0);
  77
  78   /// Destructor.
  79   virtual ~Text_Input_Device_Wrapper ();
  80
  81   /**
  82    * Modifies device settings based on passed pointer to a u_long.
  83    * Turns logging on if u_long is non-zero, off if u_long is zero,
  84    * and does nothing if the pointer is null.
  85    */
  86   virtual int modify_device_settings (void *logging);
  87
  88 protected:
  89   /// Creates a new message block, carrying data read from the
  90   /// underlying input device.
  91   virtual ACE_Message_Block *create_input_message ();
  92
  93 private:
  94   /// Length of the buffer into which to "read".
  95   size_t read_length_;
  96
  97   /// Text to "read" into the buffer.
  98   const char *text_;
  99
 100   /// Index into the string.
 101   size_t index_;
 102
 103   /// This value is 0 if logging is turned off, non-zero otherwise
 104   int logging_;
 105
 106   /// This value holds a count of packets created.
 107   u_long packet_count_;
 108 };
 109
 110 /**
 111  * @class Text_Output_Device_Wrapper
 112  *
 113  * @brief Implements a simple wrapper for a output pseudo-device.
 114  *
 115  * Data from the passed output message is printed to the standard
 116  * output stream, if logging is turned on.
 117  */
 118 class Text_Output_Device_Wrapper : public Output_Device_Wrapper_Base
 119 {
 120 public:
 121   // = Enumerated logging level flags
 122   enum Logging_Flags {NO_LOGGING = 0,
 123                       LOG_MSGS_RCVD = 2,
 124                       PRINT_MSGS_RCVD = 4};
 125
 126   /// Default constructor.
 127   Text_Output_Device_Wrapper (int logging = 0);
 128
 129   // = Command Accessible Entry Points
 130
 131   /// Consumes and possibly prints out the passed message.
 132   virtual int write_output_message (void *message);
 133
 134   /**
 135    * Modifies device settings based on passed pointer to a u_long.
 136    * Turns logging on if u_long is non-zero, off if u_long is zero,
 137    * and does nothing if the pointer is null.
 138    */
 139   virtual int modify_device_settings (void *logging);
 140
 141 private:
 142   /// This value holds the logging level.
 143   int logging_;
 144
 145   /// This value holds a count of packets received.
 146   u_long packet_count_;
 147 };
 148
 149 /**
 150  * @class User_Input_Task
 151  *
 152  * @brief Read user actions on the Timer_Queue from stdin.
 153  *
 154  * This class reads user input from stdin. The commands allow
 155  * the control of a Timer_Queue, which is dispatched by another
 156  * thread.
 157  */
 158 class User_Input_Task : public ACE_Task_Base
 159 {
 160 public:
 161   // = Trait for command accessible entry points.
 162
 163   typedef int (User_Input_Task::*ACTION) (void *);
 164
 165   /// Constructor.
 166   User_Input_Task (Bounded_Packet_Relay *relay,
 167                    Thread_Timer_Queue *queue,
 168                    Thread_Bounded_Packet_Relay_Driver &timer_queue_driver);
 169
 170   /// Destructor.
 171   virtual ~User_Input_Task ();
 172
 173   /// This method runs the event loop in the new thread.
 174   virtual int svc ();
 175
 176   // = Some helper methods.
 177
 178   /// Sets the number of packets for the next transmission.
 179   int set_packet_count (void *);
 180
 181   /// Sets the input device packet arrival period (usecs) for the next
 182   /// transmission.
 183   int set_arrival_period (void *);
 184
 185   /// Sets the period between output device sends (usecs) for the next
 186   /// transmission.
 187   int set_send_period (void *);
 188
 189   /// Sets a limit on the transmission duration (usecs).
 190   int set_duration_limit (void *);
 191
 192   /// Sets logging level (0 or 1) for output device for the next
 193   /// transmission.
 194   int set_logging_level (void *);
 195
 196   /// Runs the next transmission (if one is not in progress).
 197   int run_transmission (void *);
 198
 199   /// Ends the current transmission (if one is in progress).
 200   int end_transmission (void *);
 201
 202   /// Reports statistics for the previous transmission (if one is not
 203   /// in progress).
 204   int report_stats (void *);
 205
 206   /// Shuts down the task.
 207   int shutdown (void *);
 208
 209   /// Helper method: clears all timers.
 210   int clear_all_timers ();
 211
 212 private:
 213   /// How many microseconds are in a second.
 214   const int usecs_;
 215
 216   /// The bounded packet relay.
 217   Bounded_Packet_Relay *relay_;
 218
 219   /// The timer queue implementation.
 220   Thread_Timer_Queue *queue_;
 221
 222   /// The thread timer queue test driver.
 223   Thread_Bounded_Packet_Relay_Driver &driver_;
 224 };
 225
 226 /**
 227  * @class BPR_Handler_Base
 228  *
 229  * @brief Base event handler class for bounded packet relay example.
 230  *
 231  * The base class provides a helper method that derived classes
 232  * can register as a deferred execution callback that will cancel
 233  * all timers in the underlying timer queue, and then delete "this".
 234  */
 235 class BPR_Handler_Base : public ACE_Event_Handler
 236 {
 237 public:
 238   // = Trait for command accessible entry points.
 239
 240   typedef int (BPR_Handler_Base::*ACTION) (void *);
 241
 242
 243   /// Constructor.
 244   BPR_Handler_Base (Bounded_Packet_Relay &relay,
 245                     Thread_Timer_Queue &queue);
 246
 247   /// Destructor.
 248   virtual ~BPR_Handler_Base ();
 249
 250   // = Command accessible entry points.
 251
 252   /// Helper method: clears all timers.
 253   virtual int clear_all_timers (void *);
 254
 255 protected:
 256   /// Stores a reference to the relay object on which to invoke
 257   /// the appropritate calls when the timer expires.
 258   Bounded_Packet_Relay &relay_;
 259
 260   /// Store a reference to the timer queue, in which to re-register
 261   /// the send timer and handler if there are still sends to perform.
 262   Thread_Timer_Queue &queue_;
 263 };
 264
 265 class Send_Handler;
 266
 267 /**
 268  * @class Send_Handler
 269  *
 270  * @brief Event handler for message send timeout events.
 271  *
 272  * The <handle_timeout> hook method calls the relay's send
 273  * method and decrements its count of messages to send.
 274  * If there are still messages to send, it re-registers itself
 275  * with the timer queue.  Otherwise it calls the relay's end
 276  * transmission method, and registers a deferred execution
 277  * callback to clear the timer queue, and then delete "this".
 278  */
 279 class Send_Handler : public BPR_Handler_Base
 280 {
 281 public:
 282   // = Trait for command accessible entry points.
 283
 284   typedef int (Send_Handler::*ACTION) (void *);
 285
 286   /// Constructor.
 287   Send_Handler (u_long send_count,
 288                 const ACE_Time_Value &duration,
 289                 Bounded_Packet_Relay &relay,
 290                 Thread_Timer_Queue &queue,
 291                 Thread_Bounded_Packet_Relay_Driver &driver);
 292
 293   /// Destructor.
 294   virtual ~Send_Handler ();
 295
 296   /// Call back hook.
 297   virtual int handle_timeout (const ACE_Time_Value &current_time,
 298                               const void *arg);
 299
 300   /// Cancellation hook.
 301   virtual int cancelled ();
 302
 303   // = Command accessible entry points.
 304
 305   /// Helper method: re-registers this handler.
 306   virtual int reregister (void *timeout);
 307
 308 private:
 309   /// Count of the number of messages to send from the
 310   /// relay object to the output device object.
 311   u_long send_count_;
 312
 313   /// Stores the expected duration until expiration, and is used to
 314   /// re-register the handler if there are still sends to perform.
 315   ACE_Time_Value duration_;
 316
 317   /// Reference to the driver that will redisplay the user input menu.
 318   Thread_Bounded_Packet_Relay_Driver &driver_;
 319 };
 320
 321 /**
 322  * @class Termination_Handler
 323  *
 324  * @brief Event handler for end transmission timeout events.
 325  *
 326  * The <handle_timeout> hook method calls the relay's end
 327  * transmission method, then registers a deferred execution
 328  * callback to clear all timers and then delete "this".
 329  */
 330 class Termination_Handler : public BPR_Handler_Base
 331 {
 332 public:
 333   /// Constructor.
 334   Termination_Handler (Bounded_Packet_Relay &relay,
 335                        Thread_Timer_Queue &queue,
 336                        Thread_Bounded_Packet_Relay_Driver &driver);
 337
 338   /// Destructor.
 339   virtual ~Termination_Handler ();
 340
 341   /// Call back hook.
 342   virtual int handle_timeout (const ACE_Time_Value &current_time,
 343                               const void *arg);
 344
 345   /// Cancellation hook.
 346   virtual int cancelled ();
 347
 348 private:
 349   /// Reference to the driver that will redisplay the user input menu.
 350   Thread_Bounded_Packet_Relay_Driver &driver_;
 351 };
 352
 353 /**
 354  * @class Thread_Bounded_Packet_Relay_Driver
 355  *
 356  * @brief Implements an example application that exercises
 357  * <Thread_Timer_Queue> timer queue.
 358  *
 359  * This class implements a simple test driver for the
 360  * <Thread_Timer_Queue>.  The <display_menu> hook method is
 361  * called from the base class to print a menu specific to the
 362  * thread implementation of the timer queue.
 363  */
 364 class Thread_Bounded_Packet_Relay_Driver : public Bounded_Packet_Relay_Driver <Thread_Timer_Queue>
 365 {
 366 public:
 367   // = Trait for commands issued from this driver
 368   typedef ACE_Command_Callback<User_Input_Task, User_Input_Task::ACTION> MYCOMMAND;
 369
 370   /// Constructor.
 371   Thread_Bounded_Packet_Relay_Driver (Bounded_Packet_Relay *relay);
 372
 373   /// Destructor.
 374   virtual ~Thread_Bounded_Packet_Relay_Driver ();
 375
 376   /// Displays the user menu.
 377   virtual int display_menu ();
 378
 379   /// Initializes the driver.
 380   virtual int init ();
 381
 382   /// Run the driver.
 383   virtual int run ();
 384
 385 private:
 386   /// User input task, subclassed from ACE_Task.
 387   User_Input_Task input_task_;
 388 };
 389
 390 #endif /* _THREAD_BOUNDED_PACKET_RELAY_H_ */