ACE/ace/Synch_Options.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file   Synch_Options.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //==========================================================================
  10
  11 #ifndef ACE_SYNCH_OPTIONS_H
  12 #define ACE_SYNCH_OPTIONS_H
  13
  14 #include /**/ "ace/pre.h"
  15
  16 #include /**/ "ace/ACE_export.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include "ace/Time_Value.h"
  23
  24 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  25
  26 /**
  27  * @class ACE_Synch_Options
  28  *
  29  * @brief Contains the values of options used to determine the
  30  * synchronous and asynchronous behavior.
  31  *
  32  * The supported set of options is depicted in the following table.
  33  * The Reactor column indicates whether or not the USE_REACTOR option is
  34  * supplied.
  35  * The Timeout column specifies the period of time specified by the object;
  36  * Unused implies that USE_TIMEOUT is not included in the options and the
  37  * default timeout value, ACE_Time_Value::zero, is specified, either
  38  * explicitly or by default.
  39  *
  40  * <TABLE>
  41  * <TR><TD align="center"><B>Reactor</B></TD><TD align="center"><B>Timeout</B></TD><TD><B>Behavior</B></TD></TR>
  42  * <TR><TD>yes</TD><TD>Unused</TD><TD>Infinite timeout (using Reactor);
  43  *                                    this is the default.</TD></TR>
  44  * <TR><TD>yes</TD><TD>time</TD><TD>Try asynch transaction for the
  45  *                                 specified time (using Reactor)</TD></TR>
  46  * <TR><TD>yes</TD><TD>0,0</TD><TD>Poll; try, if EWOULDBLOCK, return
  47  *                                 immediately (using Reactor)</TD></TR>
  48  * <TR><TD>no</TD><TD>Unused</TD><TD>Block until completion (don't use Reactor)</TD></TR>
  49  * <TR><TD>no</TD><TD>time</TD><TD>Wait up to specified amount of time for
  50  *                                 completion (don't use Reactor)</TD></TR>
  51  * <TR><TD>no</TD><TD>0,0</TD><TD>Poll and return immediately</TD></TR>
  52  * </TABLE>
  53  */
  54 class ACE_Export ACE_Synch_Options
  55 {
  56 public:
  57   /// Options flags for controlling synchronization.
  58   /**
  59    * Note that these flags can be bit-wise "or'd" together if both
  60    * options are desired.
  61    */
  62   enum
  63   {
  64     /// Use the Reactor.
  65     USE_REACTOR = 01,
  66     /// Use the supplied timeout value.
  67     USE_TIMEOUT = 02
  68   };
  69
  70   /**
  71    * Initialize the object to default values unless specified otherwise.
  72    *
  73    * @param options Specifies the options to use; default is neither option
  74    *                (no reactor, no timeout).
  75    * @param timeout Specifies the period of time to use for the operation's
  76    *                timeout. The default is ACE_Time_Value::zero, noted as
  77    *                0,0 in the behavior options table. If a non-zero timeout
  78    *                is specified, the USE_TIMEOUT option is added to
  79    *                @a options.
  80    *                To use a zero timeout, USE_TIMEOUT must be explicitly
  81    *                specified in @a options.
  82    * @param arg     A completion tag that can be passed through the options;
  83    *                the class using ACE_Synch_Options can access this.
  84    *                ACE_Synch_Options makes no use of it internally.
  85    */
  86   ACE_Synch_Options (unsigned long options = 0,
  87                      const ACE_Time_Value &timeout = ACE_Time_Value::zero,
  88                      const void *arg = 0);
  89
  90   /// Initialize the object; arguments are the same as for the
  91   /// constructor.
  92   void set (unsigned long options = 0,
  93             const ACE_Time_Value &timeout = ACE_Time_Value::zero,
  94             const void *arg = 0);
  95
  96   /// Returns true if the specified option(s) are enabled, false otherwise.
  97   bool operator[] (unsigned long option) const;
  98
  99   /// Adds the specified option(s) to the object; does not replace them.
 100   void operator= (unsigned long option);
 101
 102   /// Returns the "magic cookie" argument.
 103   const void *arg (void) const;
 104
 105   /// Set the "magic cookie" argument.
 106   void arg (const void *);
 107
 108   /// Returns a reference to the ACE_Time_Value.  This value only makes
 109   /// sense if (*this)[USE_TIMEOUT] is true.
 110   const ACE_Time_Value &timeout (void) const;
 111
 112   /// Set the timeout value. This method does not alter the options; in
 113   /// particular, it doesn't add USE_TIMEOUT to the options when a non-zero
 114   /// timeout is specified as the constructor and set() do.
 115   void timeout (const ACE_Time_Value &tv);
 116
 117   /**
 118    * Returns a timeout pointer if (*this)[USE_TIMEOUT] is true, else 0.
 119    * This should be used with care, e.g., the timeout pointer should not
 120    * be stored in a manner that will lead to dangling pointers.
 121    */
 122   const ACE_Time_Value *time_value (void) const;
 123
 124   // = Static data members (singletons)
 125
 126   /// This is the default setting for options, which will block
 127   /// synchronously.
 128   static ACE_Synch_Options defaults;
 129
 130   /// This is the default synchronous setting.
 131   static ACE_Synch_Options synch;
 132
 133   /// This is the default asynchronous setting.
 134   static ACE_Synch_Options asynch;
 135
 136   /// Dump the state of an object.
 137   void dump (void) const;
 138
 139   /// Declare the dynamic allocation hooks.
 140   ACE_ALLOC_HOOK_DECLARE;
 141
 142 private:
 143   /// Keeps track of the enabled options.
 144   unsigned long options_;
 145
 146   /// Amount of time to wait for timeouts.
 147   ACE_Time_Value timeout_;
 148
 149   /**
 150    * "Magic cookie" always passed in as an argument to the ACE_Reactor's
 151    * schedule_timer() method.  Used to communicate values for
 152    * asynchronous programming.
 153    */
 154   const void *arg_;
 155 };
 156
 157 ACE_END_VERSIONED_NAMESPACE_DECL
 158
 159 #include /**/ "ace/post.h"
 160
 161 #endif /* ACE_SYNCH_OPTIONS_H */