dep/ACE_wrappers/ace/Synch_Options.h

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