00001 ///////////////////////////////////////////////////////////////////////////////////////// 00002 /// \file requests.h 00003 /// \brief Declaration of the request classes accessible from the atomic classes. 00004 /// 00005 ///////////////////////////////////////////////////////////////////////////////////////// 00006 /// \attention 00007 /// PORTIONS COPYRIGHT (C) 2003 AYRES SOWELL ASSOCIATES, INC. \n 00008 /// PORTIONS COPYRIGHT (C) 2003 THE REGENTS OF THE UNIVERSITY OF CALIFORNIA . 00009 /// PENDING APPROVAL BY THE US DEPARTMENT OF ENERGY. ALL RIGHTS RESERVED. 00010 /// 00011 ///////////////////////////////////////////////////////////////////////////////////////// 00012 /// \author Dimitri Curtil (LBNL/SRG) 00013 /// \date February 10, 2003 00014 ///////////////////////////////////////////////////////////////////////////////////////// 00015 00016 00017 00018 #if !defined(__REQUESTS_H__) 00019 #define __REQUESTS_H__ 00020 00021 00022 // Gets rid of warning messages about dll-interface for private data member 00023 // Message shows typically with std classes, e.g., std::string, std::exception, ... 00024 #pragma warning(disable:4251) 00025 #pragma warning(disable:4275) 00026 00027 00028 #include <string> 00029 00030 #include "types.h" // for AtomicTypes 00031 #include "compat.h" // for CLASS_DECLSPEC 00032 #include "exceptions.h" // for SPARK::XInitialization 00033 00034 00035 ///////////////////////////////////////////////////////////////////////////////////////// 00036 // Forward declaration 00037 ///////////////////////////////////////////////////////////////////////////////////////// 00038 namespace SPARK { 00039 class TProblem; 00040 class TInverse; 00041 class TObject; 00042 }; // namespace SPARK 00043 00044 00045 ///////////////////////////////////////////////////////////////////////////////////////// 00046 /// \namespace SPARK::Requests 00047 /// \brief Declarations of classes and functions needed to send/dispatch/process 00048 /// the %SPARK requests 00049 ///////////////////////////////////////////////////////////////////////////////////////// 00050 00051 namespace SPARK { namespace Requests { 00052 00053 // Forward declaration 00054 class TManager; 00055 00056 00057 ///////////////////////////////////////////////////////////////////////////////////// 00058 /// \class THeader 00059 /// \brief Describes where the request is sent from and the target problem. 00060 /// Used by the TDispatcher class to dispatch requests. 00061 class CLASS_DECLSPEC THeader { 00062 public: 00063 ///////////////////////////////////////////////////////////////////////////////// 00064 // Structors 00065 ///////////////////////////////////////////////////////////////////////////////// 00066 00067 /// Constructs header for request sent by TObject object 00068 THeader(const TObject* from, const TProblem* to, const char* context); 00069 /// Constructs header for request sent by TInverse object 00070 THeader(const TInverse* from, const TProblem* to, const char* context); 00071 /// Constructs header for request sent by TProblem object 00072 THeader(const TProblem* from, const TProblem* to, const char* context); 00073 /// Copy constructor 00074 THeader(const THeader& header); 00075 /// Trivial destructor 00076 ~THeader() SPARK_NOT_THROWING 00077 {} 00078 00079 00080 ///////////////////////////////////////////////////////////////////////////////// 00081 // Operations 00082 ///////////////////////////////////////////////////////////////////////////////// 00083 00084 /// Returns atomic type of sender object 00085 SPARK::AtomicTypes GetAtomicType() const { return AtomicType; } 00086 00087 /// Returns true if external request 00088 bool IsExternal() const { return External; } 00089 /// Returns true if internal request 00090 bool IsInternal() const { return !IsExternal(); } 00091 00092 /// Returns context as const char* 00093 const char* GetContext() const { return Context; } 00094 /// Returns name of sender object as const char* 00095 const char* GetSenderName() const { return SenderName; } 00096 /// Returns name of target problem as const char* 00097 const char* GetTargetName() const; 00098 00099 00100 private: 00101 THeader(); 00102 THeader& operator=(const THeader& ); 00103 00104 friend class TDispatcher; 00105 00106 ///////////////////////////////////////////////////////////////////////////////// 00107 // Private data 00108 ///////////////////////////////////////////////////////////////////////////////// 00109 bool External; /// Request type (external if true or internal if false) 00110 SPARK::AtomicTypes AtomicType; /// Obtained from sender 00111 const SPARK::TProblem* Target; /// TProblem object that the request will affect 00112 const char* SenderName; /// Name of sender 00113 const char* Context; /// User-specified context (not used internally except for debugging) 00114 00115 }; 00116 ///////////////////////////////////////////////////////////////////////////////////// 00117 00118 00119 ///////////////////////////////////////////////////////////////////////////////////// 00120 /// \class TDispatcher 00121 /// \brief Wrapper class that defines a static function for each request that can be 00122 /// sent from an atomic class. Use in coordination with the class THeader for 00123 /// the request addressing. 00124 /// \note The dispatch functions return true if the dispatcher was capable to pass 00125 /// the request to the desired target problem. Otherwise, the functions return 00126 /// false to indicate that the request will not be taken into account. 00127 class CLASS_DECLSPEC TDispatcher { 00128 public: 00129 00130 ///////////////////////////////////////////////////////////////////////////////// 00131 /// \name Requests processed when detected 00132 //@{ 00133 00134 /// \brief Aborts the simulation by exiting "cleanly" from the process 00135 /// 00136 /// \param header Request header 00137 static bool abort(const THeader& header); 00138 00139 //@} 00140 ///////////////////////////////////////////////////////////////////////////////// 00141 00142 00143 ///////////////////////////////////////////////////////////////////////////////// 00144 /// \name Requests processed only after a successful step 00145 //@{ 00146 00147 /// \brief Stops the simulation after the next successful step. 00148 /// 00149 /// \note Simulation can be resumed with a subsequent call to TProblem::Simulate() 00150 /// in the driver function. 00151 /// 00152 /// \param header Request header 00153 static bool stop(const THeader& header); 00154 00155 /// \brief Sets the time <code>time</code> at which the simulation will be stopped 00156 /// 00157 /// This request is accepted only if the requested stop time is ahead of the 00158 /// current global time of the simulator. It will however overwrite a previous 00159 /// stop time request if the new one indicates an earlier stopping time. 00160 /// The stop time does not overwrite the final time specified in the runtime 00161 /// control parameters. 00162 /// 00163 /// \param header Request header 00164 /// \param time Stopping time 00165 static bool set_stop_time(const THeader& header, double time); 00166 00167 00168 /// \brief Generates a "forced" report at the current time 00169 /// 00170 /// \param header Request header 00171 static bool report(const THeader& header); 00172 00173 /// \brief Generates a snapshot file named filename where filename can include a valid path 00174 /// 00175 /// \note Only one snapshot file can be generated per step. Subsequent snapshot 00176 /// requests will be discarded. 00177 /// \param filename is the name of the snapshot file to be generated, specified as <code>const char*</code> 00178 /// 00179 /// \param header Request header 00180 /// \param filename Name of the snapshot file 00181 static bool snapshot(const THeader& header, const char* filename); 00182 00183 00184 /// \brief Forces the time stepper to synchronize with time, whereby time > current time 00185 /// 00186 /// \param header Request header 00187 /// \param time Meeting point 00188 static bool set_meeting_point(const THeader& header, double time); 00189 00190 /// \brief Clears all meeting points assumulated so far through synchronize requests 00191 /// 00192 /// \param header Request header 00193 static bool clear_meeting_points(const THeader& header); 00194 00195 00196 /// \brief Restarts the simulation with a static step in order to perform a 00197 /// consistent initialization calculation 00198 /// 00199 /// \param header Request header 00200 static bool restart(const THeader& header); 00201 00202 //@} 00203 ///////////////////////////////////////////////////////////////////////////////// 00204 00205 00206 ///////////////////////////////////////////////////////////////////////////////// 00207 /// \name Restricted requests 00208 /// 00209 /// These requests are processed if and only if: 00210 /// - they are external requests (i.e., "to" and "from" SPARK::TProblem addresses in SPARK::THeader are the same) 00211 /// - they are internal requests sent from integrator classes only. 00212 /// 00213 //@{ 00214 00215 /// \brief Sets the time step h for the next dynamic step 00216 /// 00217 /// The time step h is a candidate time step. There is no guarantee that it 00218 /// will be used to step forward for the next dynamic step. Essentially, the 00219 /// smallest candidate time step will be passed to the clock manager that will 00220 /// decide about the next time step to try. 00221 /// 00222 /// \param header Request header 00223 /// \param h Candidate time step 00224 static bool set_time_step(const THeader& header, double h); 00225 00226 /// \brief Sets dynamic stepper that will be used from now on for all dynamic steps 00227 /// 00228 /// \note Only the default time stepper is implemented in the current version of %SPARK. 00229 /// 00230 /// \param header Request header 00231 static bool set_dynamic_stepper(const THeader& header); 00232 00233 //@} 00234 ///////////////////////////////////////////////////////////////////////////////// 00235 00236 00237 private: 00238 static SPARK::TProblem& Dispatch(const THeader& header) SPARK_THROWING( (SPARK::XInitialization) ); 00239 static SPARK::Requests::TManager& Activate(SPARK::TProblem& target) SPARK_THROWING( (SPARK::XInitialization) ); 00240 00241 }; 00242 ///////////////////////////////////////////////////////////////////////////////////// 00243 00244 00245 }; }; // namespace SPARK::Requests 00246 ///////////////////////////////////////////////////////////////////////////////////////// 00247 00248 00249 #endif // __REQUESTS_H__ 00250 00251 00252