*** empty log message ***

7 files changed, 127 insertions, 49 deletions

diff --git a/examples/Timer_Queue/Async_Timer_Queue_Test.cpp b/examples/Timer_Queue/Async_Timer_Queue_Test.cpp
index 1a325f05c03..bc07c931a4e 100644
--- a/examples/Timer_Queue/Async_Timer_Queue_Test.cpp
+++ b/examples/Timer_Queue/Async_Timer_Queue_Test.cpp
@@ -23,6 +23,7 @@
 
 #include "Async_Timer_Queue_Test.h"
 
+// Hook method that is called to handle the expiration of a timer.
 int 
 Async_Timer_Handler::handle_timeout (const ACE_Time_Value &tv,
 			       const void *arg)
@@ -64,6 +65,8 @@ Async_Timer_Queue::instance (void)
   return Async_Timer_Queue::instance_;
 }
 
+// Sets the signal set to mask, for the timer queue.
+
 Async_Timer_Queue::Async_Timer_Queue (ACE_Sig_Set *ss)
   : tq_ (ss)
 {
@@ -158,6 +161,9 @@ Async_Timer_Queue::cancel_timer (void *argument)
 int
 Async_Timer_Queue::list_timer (void *argument)
 {
+  // Macro to avoid "warning: unused parameter" type warning.
+  ACE_UNUSED_ARG (argument);
+
   // Display an error message.
   ACE_ERROR_RETURN ((LM_ERROR, "invalid input\n"), 0);
 }
@@ -168,6 +174,9 @@ Async_Timer_Queue::list_timer (void *argument)
 int
 Async_Timer_Queue::shutdown_timer (void *argument)
 {
+  // Macro to avoid "warning: unused parameter" type warning.
+  ACE_UNUSED_ARG (argument);
+
   // Display an error message.
   ACE_ERROR_RETURN ((LM_ERROR, "invalid input\n"), 0);
 }
diff --git a/examples/Timer_Queue/Async_Timer_Queue_Test.h b/examples/Timer_Queue/Async_Timer_Queue_Test.h
index 95dd6def6c9..8439aa9c45e 100644
--- a/examples/Timer_Queue/Async_Timer_Queue_Test.h
+++ b/examples/Timer_Queue/Async_Timer_Queue_Test.h
@@ -99,13 +99,11 @@ class Async_Timer_Queue_Test_Driver : public Timer_Queue_Test_Driver <Async_Time
 public:
   Async_Timer_Queue_Test_Driver (void);
 
-  // Print menu of options.
-
   virtual int display_menu (void);
-
-  // Initializes the driver's internal variables inherited from the parent
+  // Print menu of options.
 
   virtual int init (void);
+  // Initializes the driver's internal variables inherited from the parent
 };
 
 #endif /* _ASYNC_TIMER_QUEUE_TEST_H_ */
diff --git a/examples/Timer_Queue/Driver.h b/examples/Timer_Queue/Driver.h
index f59a42cf406..34f3645c930 100644
--- a/examples/Timer_Queue/Driver.h
+++ b/examples/Timer_Queue/Driver.h
@@ -42,8 +42,10 @@ typedef ACE_Thread_Timer_Queue_Adapter<Timer_Heap>
 template <class RECEIVER, class ACTION>
 class Command 
   // = TITLE
-  // @@ Please add a more descriptive title here...
-  //    Command
+  //    Defines an abstract class that allows us to invoke commands
+  //    without knowing anything about the implementation.  This class
+  //    is used in the <Timer_Queue_Test_Driver> to invoke operations
+  //    of the driver.
   //
   // = DESCRIPTION
   //    This class declares an interface to execute operations,
@@ -53,10 +55,11 @@ class Command
 {
 public:
   Command (RECEIVER &recvr, ACTION action);
-  // @@ Please add a comment.
+  // Sets the <receiver_> of the Command to recvr, and the 
+  // <action_> of the Command to <action>.
 
   virtual int execute (void *arg);
-  // @@ Please add a comment.
+  // Invokes the method <action_> from the object <receiver_>.
 
 private:
   RECEIVER &receiver_;
@@ -69,12 +72,11 @@ private:
 template <class TQ, class RECEIVER, class ACTION>
 class Timer_Queue_Test_Driver
   // = TITLE 
-  // @@ Please add a more descriptive title here...
-  //    Timer_Queue_Test_Driver
+  //    Defines a class that provides a simmple implementation for 
+  //      a test driver for timer queues.  
   //
   // = DESCRIPTION
-  //    This class implements a test driver for timer queues.  This is
-  //    the place where the common code to test the different
+  //    This is the place where the common code to test the different
   //    implementations of the timer queue resides.  This class has
   //    the logic for the parse_commands() method, the run_test(),
   //    read_input() and the get_next_request().  Subclasses can
@@ -82,20 +84,31 @@ class Timer_Queue_Test_Driver
   //    to that implementation.
 {
 public:
-  // @@ Please comment all of these methods.
   virtual int parse_commands (const char *buf);
+  // Breaks up the input string buffer into pieces and executes
+  // the appropriate method to handle that operation.
 
   virtual int run_test (void);
+  // This is the main entry point to the test driver.  The user
+  // of the class should normally invoke this method.
+  // Returns 0 when successful, or 0 otherwise.
   
   virtual int get_next_request (void);
+  // This internal method gets the next request from the user.
+  // Returns -1 when user wants to exit.  Returns 0 otherwise.
 
   virtual ssize_t read_input (char *buf, size_t bufsiz);
+  // Reads input from the user into the buffer <buf> with a maximum
+  // of <bufsiz> bytes.  Returns the amount of bytes actually read
+  // Otherwise, a -1 is returned and errno is set to indicate the error.
 
   // = Template Methods.
     
   virtual int display_menu (void)=0;
+  // Prints the user interface for the driver to STDOUT.
   
   virtual int init (void)=0;
+  // Initializes values and operations for the driver.
   
 protected:
   TQ timer_queue_;
diff --git a/examples/Timer_Queue/Reactor_Timer_Queue_Test.cpp b/examples/Timer_Queue/Reactor_Timer_Queue_Test.cpp
index 74f3ca49ce5..c8283b09ffb 100644
--- a/examples/Timer_Queue/Reactor_Timer_Queue_Test.cpp
+++ b/examples/Timer_Queue/Reactor_Timer_Queue_Test.cpp
@@ -27,11 +27,6 @@
 static const int NO_OF_IO_HANDLERS = 5;
 #define  REACTOR  ACE_Reactor::instance ()
 
-// constructor
-
-Reactor_Timer_Handler::Reactor_Timer_Handler (void)
-{}
-
 void 
 Reactor_Timer_Handler::set_timer_id (long tid)
 {
@@ -42,6 +37,9 @@ int
 Reactor_Timer_Handler::handle_timeout (const ACE_Time_Value &tv,
 			       const void *)
 {
+  // Macro to avoid "warning: unused parameter" type warning.
+  ACE_UNUSED_ARG (tv);
+
   ACE_Time_Value txv = ACE_OS::gettimeofday ();
   ACE_DEBUG ((LM_DEBUG, "\nTimer #%d fired at %d.%06d (%T)!\n",
 	      this->tid_, txv.sec (), txv.usec ()));
@@ -103,6 +101,9 @@ Input_Handler::cancel_timer (void *argument)
 int
 Input_Handler::shutdown_timer (void *argument)
 {
+  // Macro to avoid "warning: unused parameter" type warning.
+  ACE_UNUSED_ARG (argument);
+
   this->done_ = 1;
   ACE_DEBUG ((LM_DEBUG, "Shutting down event loop\n"));
   return -1;
@@ -111,6 +112,9 @@ Input_Handler::shutdown_timer (void *argument)
 int
 Input_Handler::list_timer (void *argument)
 {
+  // Macro to avoid "warning: unused parameter" type warning.
+  ACE_UNUSED_ARG (argument);
+
   ACE_Timer_Queue_Iterator &iter = this->tq_->iter ();
   ACE_DEBUG ((LM_DEBUG, "\n\nTimers in queue:\n"));
           
@@ -122,7 +126,6 @@ Input_Handler::list_timer (void *argument)
 		  tn->get_timer_value ().sec (),
 		  tn->get_timer_value ().usec ()));
     }
-
   return 0;
 }
 
@@ -133,7 +136,7 @@ Input_Handler::handle_input (ACE_HANDLE)
 }
 
 Reactor_Timer_Queue_Test_Driver::Reactor_Timer_Queue_Test_Driver (void)
-  : thandler (&timer_queue_, *this)
+  : thandler_ (&timer_queue_, *this)
 {
 }
 
@@ -160,27 +163,30 @@ Reactor_Timer_Queue_Test_Driver::init (void)
 
   // initialize <Command>s with their corresponding <Input_Handler>  methods.
   ACE_NEW_RETURN (schedule_cmd_, 
-		  COMMAND (thandler, &Input_Handler::schedule_timer),
+		  COMMAND (thandler_, &Input_Handler::schedule_timer),
 		  -1);
   
   ACE_NEW_RETURN (cancel_cmd_,
-		  COMMAND (thandler, &Input_Handler::cancel_timer),
+		  COMMAND (thandler_, &Input_Handler::cancel_timer),
 		  -1);
 
   ACE_NEW_RETURN (list_cmd_,
-		  COMMAND (thandler, &Input_Handler::list_timer),
+		  COMMAND (thandler_, &Input_Handler::list_timer),
 		  -1);
 
   ACE_NEW_RETURN (shutdown_cmd_,
-		  COMMAND (thandler, &Input_Handler::shutdown_timer),
+		  COMMAND (thandler_, &Input_Handler::shutdown_timer),
 		  -1);
 
   REACTOR->set_timer_queue (&timer_queue_);
 
-  ACE::register_stdin_handler (&thandler, REACTOR,
+  ACE::register_stdin_handler (&thandler_, REACTOR,
                                ACE_Thread_Manager::instance ());
 
+  // print the menu of options.
   this->display_menu ();
+
+  return 0;
 }
 
 // run test was overrun due to the reactive way of handling input.
@@ -193,7 +199,7 @@ Reactor_Timer_Queue_Test_Driver::run_test (void)
   this->init ();
 
   // Run until we say stop.
-  while (thandler.done () == 0)
+  while (thandler_.done () == 0)
     REACTOR->handle_events ();
 
   ACE_DEBUG ((LM_DEBUG, "TIMER TEST ENDED\n"));
diff --git a/examples/Timer_Queue/Reactor_Timer_Queue_Test.h b/examples/Timer_Queue/Reactor_Timer_Queue_Test.h
index 153c22509b6..a1ea8fd147c 100644
--- a/examples/Timer_Queue/Reactor_Timer_Queue_Test.h
+++ b/examples/Timer_Queue/Reactor_Timer_Queue_Test.h
@@ -30,7 +30,9 @@ class Reactor_Timer_Queue_Test_Driver;
 
 class Input_Handler : public ACE_Event_Handler
   // = TITLE
-  //   Input_Handler
+  //   Implements the handler to be called for input events.  Also has 
+  //   the logic to handle the different timer queue operations (i.e., 
+  //   schedule, cancel, list, shutdown).
   //
   // = DESCRIPTION
   //   This class handles the reading of user input from stdin.  Also
@@ -40,16 +42,35 @@ class Input_Handler : public ACE_Event_Handler
 public:
   typedef int (Input_Handler::*ACTION) (void *);
 
-  // @@ Please comment all these methods.
   Input_Handler (ACE_Timer_Queue *tq,
 		 Reactor_Timer_Queue_Test_Driver &timer_queue_driver);
+  // Sets <done_> flag to 0, <driver_> to <timer_queue_driver> and
+  // timer queue <tq_> to <tq> 
+
   int handle_input (ACE_HANDLE);
+  // Hook method for the <ACE_Reactor> to call whenever there is input
+  // ready to be read.
 
   int done (void);
+  // returns the value for <done_> that indicates whether we are exiting
+  // the program.A value of 0 indicates that we are NOT done, 1 otherwise.
+
+  // = Hook methods to be called from <Reactor_Timer_Queue_Test_Driver>
+
   int schedule_timer (void *argument);
+  // schedule a timer.  The (void *) will be mapped to the delay parameter
+  // for the timer queue schedule method.
+
   int cancel_timer (void *argument);
+  // cancel a timer.  The (void *) will be mapped to the ID of the timer 
+  // beiing cancelled.
+
   int list_timer (void *argument);
+  // Dump the timers in the queue.  The argument is ignored.
+
   int shutdown_timer (void *argument);
+  // Processes the request to exit the timer queue application.
+  // argument is ignored.
 
 private:
   ACE_Timer_Queue *tq_;
@@ -60,28 +81,39 @@ private:
   // Flag used to close down program.
 
   Reactor_Timer_Queue_Test_Driver &driver_;
-  // Test driver.
+  // Test driver.  Used to call hook methods that are common code for all 
+  // drivers.
 };
 
 class Reactor_Timer_Queue_Test_Driver : public Timer_Queue_Test_Driver <ACE_Timer_Heap, Input_Handler, Input_Handler::ACTION>
   // = TITLE
-  //   Reactor_Timer_Queue_Test_Driver
+  //   Implements a test driver for a reactive timer queue using <ACE_Reactor>.
   //
   // = DESCRIPTION
   //   This class implements the logic to test the reactor
   //   implementation of timer queue, using an <ACE_Timer_Heap>.
 {
 public:
-  // Please comment all these methods.
   Reactor_Timer_Queue_Test_Driver (void);
+  // sets the input handler <thandler_> with <timer_queue_> from the
+  // <Timer_Queue_Test_Driver> class and a reference to "this", so the
+  // input handler can call hook methods from the driver.  Such methods are
+  // the common factored out code from other implementations of timer queues.
   
   virtual int display_menu (void);
+  // prints the menu of options.
+
   virtual int init (void);
+  // Sets the timer queue that the REACTOR will use; registers the stdin
+  // input handler with the REACTOR and sets the <Command>s that the
+  // <Timer_Queue_Test_Driver> will execute().
+
   virtual int run_test (void);
+  // Main entry point to the test driver implementation.
   
 private:
+  Input_Handler thandler_;
   // This is the stdin handler.
-  Input_Handler thandler;
 };
 
 class Reactor_Timer_Handler : public ACE_Event_Handler
@@ -89,16 +121,17 @@ class Reactor_Timer_Handler : public ACE_Event_Handler
   //     Target of the reactive timeout operation.
 {
 public:
-  // @@ Please comment all these methods.
-  Reactor_Timer_Handler (void);
-
   virtual int handle_timeout (const ACE_Time_Value &tv,
                               const void *);
+  // hook method that is called by the reactor when a timer
+  // expires.  It prints the timer ID and the time it expired.
 
   void set_timer_id (long tid);
+  // Sets the timer id for this handler <tid_> to <tid>
   
 private:
   long tid_;
+  // timer ID.
 };
 
 #endif /* _REACTOR_TIMER_QUEUE_TEST_H_ */
diff --git a/examples/Timer_Queue/Thread_Timer_Queue_Test.cpp b/examples/Timer_Queue/Thread_Timer_Queue_Test.cpp
index 11425f66a32..24f7c5f7110 100644
--- a/examples/Timer_Queue/Thread_Timer_Queue_Test.cpp
+++ b/examples/Timer_Queue/Thread_Timer_Queue_Test.cpp
@@ -73,7 +73,7 @@ Handler::cancelled (void)
 
 Input_Task::Input_Task (Thread_Timer_Queue *queue, Thread_Timer_Queue_Test_Driver &timer_queue_driver)
   : queue_ (queue),
-    usecs_ (1000000), // @@ Make this an ACE #define constant?
+    usecs_ (ACE_ONE_SECOND_IN_USECS), 
     driver_ (timer_queue_driver)
 {
 }
@@ -138,7 +138,22 @@ Input_Task::cancel_timer (void *argument)
 int
 Input_Task::list_timer (void *argument)
 {
+  // Macro to avoid "warning: unused parameter" type warning.
+  ACE_UNUSED_ARG (argument);
+
+  // Thread cancellation point, if ACE supports it.
+#if !defined (ACE_LACKS_PTHREAD_CANCEL)
+  ACE_PTHREAD_CLEANUP_PUSH(&this->queue_->lock ());
+#endif
+
+  // dump the timer queue contents.
   this->dump ();
+
+  // Thread cancellation point (POP)
+#if !defined (ACE_LACKS_PTHREAD_CANCEL)
+  ACE_PTHREAD_CLEANUP_POP(1);
+#endif
+
   return 0;
 }
 
@@ -148,6 +163,10 @@ Input_Task::list_timer (void *argument)
 int
 Input_Task::shutdown_timer (void *argument)
 {
+  // Macro to avoid "warning: unused parameter" type warning.
+  ACE_UNUSED_ARG (argument);
+
+  // -1 indicates we are shutting down the application.
   return -1;
 }
 
@@ -169,7 +188,7 @@ Input_Task::dump (void)
 // constructor
 
 Thread_Timer_Queue_Test_Driver::Thread_Timer_Queue_Test_Driver (void)
-    : input_task (&timer_queue_, *this)
+    : input_task_ (&timer_queue_, *this)
     {}
 
 int 
@@ -202,22 +221,22 @@ Thread_Timer_Queue_Test_Driver::init (void)
   // initialize the <Command> objects with their corresponding 
   // methods from <Input_Task>
   ACE_NEW_RETURN (schedule_cmd_, 
-		  COMMAND (input_task, &Input_Task::add_timer),
+		  COMMAND (input_task_, &Input_Task::add_timer),
 		  -1);
   
   ACE_NEW_RETURN (cancel_cmd_,
-		  COMMAND (input_task, &Input_Task::cancel_timer),
+		  COMMAND (input_task_, &Input_Task::cancel_timer),
 		  -1);
 
   ACE_NEW_RETURN (list_cmd_,
-		  COMMAND (input_task, &Input_Task::list_timer),
+		  COMMAND (input_task_, &Input_Task::list_timer),
 		  -1);
 
   ACE_NEW_RETURN (shutdown_cmd_,
-		  COMMAND (input_task, &Input_Task::shutdown_timer),
+		  COMMAND (input_task_, &Input_Task::shutdown_timer),
 		  -1);
 
-  if (input_task.activate () == -1)
+  if (input_task_.activate () == -1)
     ACE_ERROR_RETURN ((LM_ERROR, "cannot activate input task"), -1);
   
   if (timer_queue_.activate () == -1)
diff --git a/examples/Timer_Queue/Thread_Timer_Queue_Test.h b/examples/Timer_Queue/Thread_Timer_Queue_Test.h
index fa28bd9e18e..06bcd529c91 100644
--- a/examples/Timer_Queue/Thread_Timer_Queue_Test.h
+++ b/examples/Timer_Queue/Thread_Timer_Queue_Test.h
@@ -94,7 +94,8 @@ private:
 
 class Thread_Timer_Queue_Test_Driver : public Timer_Queue_Test_Driver <Thread_Timer_Queue, Input_Task, Input_Task::ACTION>
   // = TITLE
-  //    Thread_Timer_Queue_Test_Driver
+  //    Implements an example application that exercises <Thread_Timer_Queue> 
+  //    timer queue.
   //
   // = DESCRIPTION
   //    This class implements a simple test driver for the
@@ -110,18 +111,17 @@ public:
   virtual int run_test (void);
 
 private:
-  Input_Task input_task;
-  // @@ Please fix this by putting a trailing '_'...
+  Input_Task input_task_;
+  // Subclassed from ACE_Task.
 };
 
 class Handler : public ACE_Event_Handler 
   // = TITLE
-  //    This class implements a simple Event_Handler,
+  //     Event handler for the timer queue timeout events.
   //
   // = DESCRIPTION
-  //     The <handle_timeout> hook method justs printouts the current
-  //     time, delete this and prints the delay on the twhen it is
-  //     expired.
+  //     The <handle_timeout> hook method prints out the current
+  //     time, prints the time when this timer expired and deletes "this".
 {
 public:
   Handler (const ACE_Time_Value &expiration_time);