00001 // -*- C++ -*- 00002 00003 //========================================================================== 00004 /** 00005 * @file Synch_Options.h 00006 * 00007 * $Id: Synch_Options.h 74544 2006-09-27 21:21:16Z shuston $ 00008 * 00009 * @author Douglas C. Schmidt <schmidt@uci.edu> 00010 */ 00011 //========================================================================== 00012 00013 #ifndef ACE_SYNCH_OPTIONS_H 00014 #define ACE_SYNCH_OPTIONS_H 00015 00016 #include /**/ "ace/pre.h" 00017 00018 #include /**/ "ace/ACE_export.h" 00019 00020 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00021 # pragma once 00022 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00023 00024 #include "ace/Time_Value.h" 00025 00026 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00027 00028 /** 00029 * @class ACE_Synch_Options 00030 * 00031 * @brief Contains the values of options used to determine the 00032 * synchronous and asynchronous behavior. 00033 * 00034 * The supported set of options is depicted in the following table. 00035 * The Reactor column indicates whether or not the USE_REACTOR option is 00036 * supplied. 00037 * The Timeout column specifies the period of time specified by the object; 00038 * Unused implies that USE_TIMEOUT is not included in the options and the 00039 * default timeout value, ACE_Time_Value::zero, is specified, either 00040 * explicitly or by default. 00041 * 00042 * <TABLE> 00043 * <TR><TD align="center"><B>Reactor</B></TD><TD align="center"><B>Timeout</B></TD><TD><B>Behavior</B></TD></TR> 00044 * <TR><TD>yes</TD><TD>Unused</TD><TD>Infinite timeout (using Reactor); 00045 * this is the default.</TD></TR> 00046 * <TR><TD>yes</TD><TD>time</TD><TD>Try asynch transaction for the 00047 * specified time (using Reactor)</TD></TR> 00048 * <TR><TD>yes</TD><TD>0,0</TD><TD>Poll; try, if EWOULDBLOCK, return 00049 * immediately (using Reactor)</TD></TR> 00050 * <TR><TD>no</TD><TD>Unused</TD><TD>Block until completion (don't use Reactor)</TD></TR> 00051 * <TR><TD>no</TD><TD>time</TD><TD>Wait up to specified amount of time for 00052 * completion (don't use Reactor)</TD></TR> 00053 * <TR><TD>no</TD><TD>0,0</TD><TD>Poll and return immediately</TD></TR> 00054 * </TABLE> 00055 */ 00056 class ACE_Export ACE_Synch_Options 00057 { 00058 public: 00059 /// Options flags for controlling synchronization. 00060 /** 00061 * Note that these flags can be bit-wise "or'd" together if both 00062 * options are desired. 00063 */ 00064 enum 00065 { 00066 /// Use the Reactor. 00067 USE_REACTOR = 01, 00068 /// Use the supplied timeout value. 00069 USE_TIMEOUT = 02 00070 }; 00071 00072 /** 00073 * Initialize the object to default values unless specified otherwise. 00074 * 00075 * @param options Specifies the options to use; default is neither option 00076 * (no reactor, no timeout). 00077 * @param timeout Specifies the period of time to use for the operation's 00078 * timeout. The default is ACE_Time_Value::zero, noted as 00079 * 0,0 in the behavior options table. If a non-zero timeout 00080 * is specified, the USE_TIMEOUT option is added to 00081 * @a options. 00082 * To use a zero timeout, USE_TIMEOUT must be explicitly 00083 * specified in @a options. 00084 * @param arg A completion tag that can be passed through the options; 00085 * the class using ACE_Synch_Options can access this. 00086 * ACE_Synch_Options makes no use of it internally. 00087 */ 00088 ACE_Synch_Options (unsigned long options = 0, 00089 const ACE_Time_Value &timeout = ACE_Time_Value::zero, 00090 const void *arg = 0); 00091 00092 /// Initialize the object; arguments are the same as for the 00093 /// constructor. 00094 void set (unsigned long options = 0, 00095 const ACE_Time_Value &timeout = ACE_Time_Value::zero, 00096 const void *arg = 0); 00097 00098 /// Returns true if the specified option(s) are enabled, false otherwise. 00099 bool operator[] (unsigned long option) const; 00100 00101 /// Adds the specified option(s) to the object; does not replace them. 00102 void operator= (unsigned long option); 00103 00104 /// Returns the "magic cookie" argument. 00105 const void *arg (void) const; 00106 00107 /// Set the "magic cookie" argument. 00108 void arg (const void *); 00109 00110 /// Returns a reference to the ACE_Time_Value. This value only makes 00111 /// sense if (*this)[USE_TIMEOUT] is true. 00112 const ACE_Time_Value &timeout (void) const; 00113 00114 /// Set the timeout value. This method does not alter the options; in 00115 /// particular, it doesn't add USE_TIMEOUT to the options when a non-zero 00116 /// timeout is specified as the constructor and set() do. 00117 void timeout (const ACE_Time_Value &tv); 00118 00119 /** 00120 * Returns a timeout pointer if (*this)[USE_TIMEOUT] is true, else 0. 00121 * This should be used with care, e.g., the timeout pointer should not 00122 * be stored in a manner that will lead to dangling pointers. 00123 */ 00124 const ACE_Time_Value *time_value (void) const; 00125 00126 // = Static data members (singletons) 00127 00128 /// This is the default setting for options, which will block 00129 /// synchronously. 00130 static ACE_Synch_Options defaults; 00131 00132 /// This is the default synchronous setting. 00133 static ACE_Synch_Options synch; 00134 00135 /// This is the default asynchronous setting. 00136 static ACE_Synch_Options asynch; 00137 00138 /// Dump the state of an object. 00139 void dump (void) const; 00140 00141 /// Declare the dynamic allocation hooks. 00142 ACE_ALLOC_HOOK_DECLARE; 00143 00144 private: 00145 /// Keeps track of the enabled options. 00146 unsigned long options_; 00147 00148 /// Amount of time to wait for timeouts. 00149 ACE_Time_Value timeout_; 00150 00151 /** 00152 * "Magic cookie" always passed in as an argument to the ACE_Reactor's 00153 * <schedule_timer> method. Used to communicate values for 00154 * asynchronous programming. 00155 */ 00156 const void *arg_; 00157 }; 00158 00159 ACE_END_VERSIONED_NAMESPACE_DECL 00160 00161 #include /**/ "ace/post.h" 00162 00163 #endif /* ACE_SYNCH_OPTIONS_H */