sp_dplpexecutor.h

Go to the documentation of this file.
00001 /** @file sp_dplpexecutor.h Executor with IO device  */
00002 
00003 /* 
00004    FAU Discrete Event Systems Library (libfaudes)
00005 
00006    Copyright (C) 2008  Thomas Moor
00007 
00008 */
00009 
00010 // load configuration
00011 #include "corefaudes.h"
00012 
00013 #ifndef FAUDES_SP_DPLPEXECUTOR_H
00014 #define FAUDES_SP_DPLPEXECUTOR_H
00015 
00016 
00017 #include "tp_include.h"
00018 #include "sp_plpexecutor.h" 
00019 #include "sp_simeventset.h"
00020 #include <ctime>
00021 
00022 
00023 // use iodevice or dummy if not available
00024 #ifdef FAUDES_PLUGIN_IODEVICE
00025 #include "iop_include.h"
00026 #else
00027 namespace faudes {
00028 /** Dummy typedef in the absence of the IO Device plugin */
00029 typedef void vDevice; 
00030 }
00031 #endif
00032 
00033 namespace faudes {
00034   
00035 /**
00036  * Executer with IO device to handle external/physical events
00037  *
00038  * \section SecSimulatorDPLPEX1 External/Physical Events and Time
00039  *
00040  * This executor class is derived from the ProposingExecutor and uses a vDevice
00041  * from the IO Device Plugin to handle input and output events and physical time. 
00042  * Technically, the class provides the routine SyncStep() that has to be called periodically to
00043  * synchronize executor clock time with physical time and to perform input readings and
00044  * output writings. There is also a convenience routine SyncRun() which runs a loop
00045  * with SyncStep().
00046  *
00047  * The SyncStep() procedure implements the below stages. It returns true, if indeed
00048  * a transition was executed. It returns false on synchronistion errors or when the specified
00049  * duration expired.
00050  *    
00051  *  -  get a proposal from ProposingEcexutor
00052  *  -  if physical time is ahead of the genartors current clock time, sync time by
00053  *      ExecuteTime; in the case that this is not consistent with the proposal, 
00054  *      an error is reported;
00055  *  -  if the generators current clock time is ahead of physical time, an error is reported
00056  *  -  if a input event has been reported that can be executed at generators current time, execute it
00057  *  -  if the proposal schedules an event for the generators current time, execute it
00058  *  -  if a input event has been reported, execute it now; if this event is not accepted by the generator, report an error
00059  *  -  if the proposals time is not yet executed, wait for that amount of time to pass
00060  *       or a input event to be delivered.
00061  *
00062  *
00063  *
00064  * Naturally, the DeviceExecutor requires the IO Device plugin in order to be functional.
00065  * In the absence of the plugin, the DeviceExecutor will behave like a ProposingExecutor.
00066  *
00067  * \section SecSimulatorLPEX3 File IO
00068  *
00069  * The DeviceExecutor inherits file IO from the ProposingExecutor. The device itself 
00070  * is initialized by vDevice methods (eg configured from File) and then passed to the 
00071  * DeviceExecutor by the method Devicep(). Thus, the DeviceExecutor does not need to
00072  * implement additional token io facilities.
00073  *
00074  * @ingroup SimulatorPlugin 
00075  */
00076 
00077 class DeviceExecutor : public ProposingExecutor {  
00078 
00079 FAUDES_TYPE_DECLARATION(DeviceExecutor,DeviceExecutor,LoggingExecutor)
00080 
00081  public:
00082     
00083   /*****************************************
00084    *****************************************
00085    *****************************************
00086    *****************************************/
00087 
00088   /** @name Constructors & Destructor */
00089   /** @{ doxygen group */
00090 
00091   /**
00092    * Creates an emtpy DeviceExecutor
00093    */
00094   DeviceExecutor();
00095 
00096   /**
00097    * Copy constructor
00098    */
00099   DeviceExecutor(const DeviceExecutor&);
00100 
00101   /**
00102    * Explicit destructor
00103    */
00104   ~DeviceExecutor();
00105 
00106 
00107  /**
00108    * Dummy factory method.
00109    *
00110    * Note: the executor classes currently do not implement
00111    * faudes Type RTI related function. This factory method
00112    * is only to prevent registry error messages.
00113    */
00114   DeviceExecutor* New(void) { return new DeviceExecutor();};
00115 
00116 
00117   /** @} doxygen group */
00118 
00119   /*****************************************
00120    *****************************************
00121    *****************************************
00122    *****************************************/
00123 
00124   /** @name Re-implemenented from ParallelExecutor */
00125   /** @{ doxygen group */
00126 
00127   /**
00128    * Reset the DeviceExecutor.
00129    *
00130    * Reset the executor to its initial state and reset the device, ie clear queued
00131    * input event set outputs to a passive state
00132    *
00133    * @param seed
00134    *     Seed for PropossingExecutor random generator, 0<>system time
00135    */
00136   virtual void Reset(long int seed=0);
00137 
00138   /**
00139    * Clear all data (generators, simulation attributes etc)
00140    *
00141    * This includes the "HardwareReset" event.
00142    *
00143    */
00144   virtual void Clear(void);
00145 
00146 
00147   /**
00148    * Execute event.
00149    *
00150    * Programmatically override any internal schedules and execute the specified event.
00151    * This routine will neither synchronize generator time nor events.
00152    *
00153    * @param event
00154    *   Event by index
00155    * @return 
00156    *   True on success
00157    */
00158   bool ExecuteEvent(Idx event);
00159     
00160 
00161   /** @} doxygen group */
00162 
00163   /** @name Application Interface */
00164   /** @{ doxygen group */
00165 
00166   /**
00167    * Set tolerance for time synchonisation.
00168    *
00169    * @param maxgap
00170    *   Max acceptable amount of faudes-time units by which the generators 
00171    *   global clock may be behind physical time
00172    *
00173    */
00174   void ToleranceTime(tpTime::Type maxgap) {mMaxSyncGap=maxgap; mSyncMode |= SyncStrictTime;};
00175 
00176   /**
00177    * Modes of synchronisation
00178    */
00179   typedef enum {
00180     SyncStrictTime   =0x01,
00181     SyncStrictEvents =0x02
00182   } SyncMode;     
00183 
00184   /**
00185    * Set synchronisation flags.
00186    *
00187    * Semantics are defined via the enum typedef SyncMode.
00188    *
00189    * @param flag
00190    *   Flag word to set mode
00191    *
00192    */
00193   void ToleranceMode(int flag) {mSyncMode=flag;};
00194 
00195   /**
00196    * Execute generator clock time to sync with device time.
00197    *
00198    * If possible, execute the amount of clock time required for an
00199    * exact match. Otherwise, accept the specified tolerance. As a
00200    * last resort, issue a sync error. 
00201    *
00202    * @return
00203    *   True, on success ie synchron within tolerance.
00204    */
00205   bool SyncTime(void);
00206 
00207   /**
00208    * Execute scheduled or input events now
00209    *
00210    * If an event is scheduled for now, execute it.
00211    * Otherwise, execute a input event if such is ready.
00212    * Otherwise execute do nothing.
00213    *
00214    * @return
00215    *   Idx of event executed, 0 for no execution or error
00216    */
00217   Idx SyncEvents();
00218 
00219 
00220   /**
00221    * Wait for input events
00222    *
00223    * Wait the specified amount of time, for the proposed time to elaps,
00224    * or a input event to occur - whatever comes first.
00225    * This function will *not* synchronise with generator time. You may 
00226    * call SyncTime afterwards.
00227    *
00228    * @param duration
00229    *   Max duration to wait for
00230    * @return
00231    *   True, if input events are available
00232    */
00233   bool SyncWait(tpTime::Type duration=tpTime::Max);
00234 
00235   /**
00236    * Wait for input events
00237    *
00238    * Wait the specified amount of time, for the proposed time to elaps,
00239    * or a input event to occur - whatever comes first.
00240    * This function will *not* synchronise with generator time. You may 
00241    * call SyncTime afterwards.
00242    * 
00243    * Note that the executor does not know about msecs, and thus the core interface
00244    * referc to faudes-time units only. This function is an exception of this rule
00245    * and is for convenience only.
00246    *
00247    * @param durationms
00248    *   Max duration in msecs to wait for
00249    * @return
00250    *   True, if input events are available
00251    */
00252   bool SyncWaitMs(int durationms);
00253 
00254   /**
00255    * Execute one transition with synchronous physical signals.
00256    *
00257    * Calls SyncTime, SyncEvents and SyncWait to execute one transition.
00258    * It will, however, not pass more than the specified duration. 
00259    *
00260    * @param duration
00261    *   Max duration of execution wrt generator time, tpTime::Max for unlimited
00262    * @return
00263    *   Idx of executed event or 0 for time out or error
00264    */
00265   Idx SyncStep(tpTime::Type duration=tpTime::Max);
00266 
00267   /**
00268    * Run execution with synchronous physical signals.
00269    *
00270    * Loops SyncStep until the specified amount on time expired.
00271    *
00272    * @param duration
00273    *   Duration of execution wrt generator time, tpTime::Max for infinite
00274    * @return
00275    *  True, for no error
00276    */
00277   bool SyncRun(tpTime::Type duration=tpTime::Max);
00278 
00279   /**
00280    * Test Syncronisation
00281    *
00282    * @return True, if device time and events are in sync with
00283    *   generator time and events.
00284    *
00285    */
00286   bool IsSynchronous(void) const { return ! mSyncError; };
00287 
00288   /**
00289    * Set device.
00290    *
00291    * The device must be configured. You must start
00292    * the device befor the first call to SyncRun. Ownership of 
00293    * the device stays with the caller.
00294    *
00295    * @param dev
00296    *   IO Device to use
00297    *
00298    */
00299   void Devicep(vDevice* dev);
00300 
00301   /**
00302    * Get device.
00303    *
00304    * Retturn a refernce to the device for inspection. Note: you must not
00305    * interfear with the device during synchronuous execution.
00306    *
00307    * @return dev
00308    *   IO Device to use
00309    *
00310    */
00311   vDevice* Devicep() { return pDevice; };
00312 
00313   /**
00314    * Convenience: Reset the device.
00315    *
00316    */
00317   void DeviceReset(void);
00318 
00319   /**
00320    * Convenience: Start the device.
00321    *
00322    */
00323   void DeviceStart(void);
00324 
00325   /**
00326    * Convenience: Stop the device.
00327    *
00328    */
00329   void DeviceStop(void);
00330 
00331   /**
00332    * Query the device whther it has received an external reset request.
00333    * This method will reset the request.
00334    *
00335    * @return 
00336    *  True, if there is such a reset request
00337    */
00338   virtual bool DeviceResetRequest(void);
00339 
00340   /** @} doxygen group */
00341 
00342  protected:
00343 
00344 
00345   /** Sync error flag */
00346   bool mSyncError;
00347 
00348   /** Max gap between physical and generator clock time  */
00349   tpTime::Type mMaxSyncGap;
00350  
00351   /** Mode flags for synchronisation */
00352   int mSyncMode;
00353  
00354   /** Device reference */
00355   vDevice* pDevice;
00356 
00357   /**
00358    * Assignment method
00359    *
00360    * @param rSrc
00361    *    Source to assign from
00362    */
00363   virtual void DoAssign(const DeviceExecutor& rSrc);
00364 
00365 
00366 
00367 }; // end class DeviceExecutor
00368 
00369 
00370 
00371 } // namespace faudes
00372 
00373 
00374 #endif // .h
00375 

libFAUDES 2.23h --- 2014.04.03 --- c++ api documentaion by doxygen