ChangeLogTag:Fri Sep 8 18:25:17 UTC 2006 Steve Huston <shuston@riverace.com>

1 files changed, 48 insertions, 39 deletions

diff --git a/ACE/ace/Synch_Options.h b/ACE/ace/Synch_Options.h
index 495101aa20a..307086715c5 100644
--- a/ACE/ace/Synch_Options.h
+++ b/ACE/ace/Synch_Options.h
@@ -31,34 +31,27 @@ ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  * @brief Contains the values of options used to determine the
  * synchronous and asynchronous behavior.
  *
- * Values support the following behavior (TV == "timeout"
- * and UR == "use ACE_Reactor"):
+ * The supported set of options is depicted in the following table.
+ * The Reactor column indicates whether or not the USE_REACTOR option is
+ * supplied.
+ * The Timeout column specifies the period of time specified by the object;
+ * Unused implies that USE_TIMEOUT is not included in the options and the
+ * default timeout value, ACE_Time_Value::zero, is specified, either
+ * explicitly or by default.
  *
- * <CODE>
- * | Parameters     | Description
- * |
- * |TV   |  UR      |
- * |-----|----------|-------------------------------
- * |                |
- * |NULL | yes      | infinite timeout (using ACE_Reactor)
- * |                |
- * |time | yes      | try asynch transaction for
- * |                | the specified time (using ACE_Reactor)
- * |                |
- * |0,0  | yes      | poll; try, if EWOULDBLOCK,
- * |                | then return immediately
- * |                | (using ACE_Reactor)
- * |                |
- * |NULL | no       | block forever (don't use ACE_Reactor)
- * |                |
- * |time | no       | do a blocking transaction
- * |                | for the specified time
- * |                | (don't use ACE_Reactor)
- * |                |
- * |0,0  | no       | poll; but do not initiate a
- * |                | nonblocking transaction
- * |                | (don't use ACE_Reactor)
- * </CODE>
+ * <TABLE>
+ * <TR><TD align="center"><B>Reactor</B></TD><TD align="center"><B>Timeout</B></TD><TD><B>Behavior</B></TD></TR>
+ * <TR><TD>Unused</TD><TD>yes</TD><TD>Infinite timeout (using Reactor);
+ *                                    this is the default.</TD></TR>
+ * <TR><TD>time</TD><TD>yes</TD><TD>Try asynch transaction for the
+ *                                 specified time (using Reactor)</TD></TR>
+ * <TR><TD>0,0</TD><TD>yes</TD><TD>Poll; try, if EWOULDBLOCK, return
+ *                                 immediately (using Reactor)</TD></TR>
+ * <TR><TD>Unused</TD><TD>no</TD><TD>Block until completion (don't use Reactor)</TD></TR>
+ * <TR><TD>time</TD><TD>no</TD><TD>Wait up to specified amount of time for
+ *                                 completion (don't use Reactor)</TD></TR>
+ * <TR><TD>0,0</TD><TD>no</TD><TD>Poll and return immediately</TD></TR>
+ * </TABLE>
  */
 class ACE_Export ACE_Synch_Options
 {
@@ -72,25 +65,40 @@ public:
   {
     /// Use the Reactor.
     USE_REACTOR = 01,
-    /// Interprete the Time_Value.
+    /// Use the supplied timeout value.
     USE_TIMEOUT = 02
   };
 
-  // = Initialization methods.
-  /// Initialize the Synch_Options based on parameters.
+  /**
+   * Initialize the object to default values unless specified otherwise.
+   *
+   * @param options Specifies the options to use; default is neither option
+   *                (no reactor, no timeout).
+   * @param timeout Specifies the period of time to use for the operation's
+   *                timeout. The default is ACE_Time_Value::zero, noted as
+   *                0,0 in the behavior options table. If a non-zero timeout
+   *                is specified, the USE_TIMEOUT option is added to
+   *                @a options.
+   *                To use a zero timeout, USE_TIMEOUT must be explicitly
+   *                specified in @a options.
+   * @param arg     A completion tag that can be passed through the options;
+   *                the class using ACE_Synch_Options can access this.
+   *                ACE_Synch_Options makes no use of it internally.
+   */
   ACE_Synch_Options (unsigned long options = 0,
                      const ACE_Time_Value &timeout = ACE_Time_Value::zero,
                      const void *arg = 0);
 
-  /// Initialize the Synch_Options based on parameters.
+  /// Initialize the object; arguments are the same as for the
+  /// constructor.
   void set (unsigned long options = 0,
             const ACE_Time_Value &timeout = ACE_Time_Value::zero,
             const void *arg = 0);
 
-  /// Get method for determining which options are enabled.
-  int operator[] (unsigned long option) const;
+  /// Returns true if the specified option(s) are enabled, false otherwise.
+  bool operator[] (unsigned long option) const;
 
-  /// Set method for enabling certain options.
+  /// Adds the specified option(s) to the object; does not replace them.
   void operator= (unsigned long option);
 
   /// Returns the "magic cookie" argument.
@@ -103,14 +111,15 @@ public:
   /// sense if (*this)[USE_TIMEOUT] is true.
   const ACE_Time_Value &timeout (void) const;
 
-  /// Set the ACE_Time_Value.
+  /// Set the timeout value. This method does not alter the options; in
+  /// particular, it doesn't add USE_TIMEOUT to the options when a non-zero
+  /// timeout is specified as the constructor and set() do.
   void timeout (const ACE_Time_Value &tv);
 
   /**
-   * Returns the address of the timeout <Time_Value> if
-   * (*this)[USE_TIMEOUT] is true, else 0.  This should be used with
-   * care, e.g., the timeout pointer should not be stored in a manner
-   * that will lead to dangling pointers...
+   * Returns a timeout pointer if (*this)[USE_TIMEOUT] is true, else 0.
+   * This should be used with care, e.g., the timeout pointer should not
+   * be stored in a manner that will lead to dangling pointers.
    */
   const ACE_Time_Value *time_value (void) const;