libFAUDES

Sections

Index

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 sensor and actuator 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 sensor readings and
00044  * actuator 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 sensor 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 sensor 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 sensor 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  public:
00080     
00081   /*****************************************
00082    *****************************************
00083    *****************************************
00084    *****************************************/
00085 
00086   /** @name Constructors & Destructor */
00087   /** @{ doxygen group */
00088 
00089   /**
00090    * Creates an emtpy DeviceExecutor
00091    */
00092   DeviceExecutor();
00093 
00094   /**
00095    * Explicit destructor
00096    */
00097   ~DeviceExecutor();
00098 
00099 
00100   /** @} doxygen group */
00101 
00102   /*****************************************
00103    *****************************************
00104    *****************************************
00105    *****************************************/
00106 
00107   /** @name Re-implemenented from ParallelExecutor */
00108   /** @{ doxygen group */
00109 
00110   /**
00111    * Reset the DeviceExecutor.
00112    *
00113    * Reset the executor to its initial state and reset the device, ie clear queued
00114    * sensor event set actuators to a passive state
00115    *
00116    * @param seed
00117    *     Seed for PropossingExecutor random generator, 0<>system time
00118    */
00119   virtual void Reset(long int seed=0);
00120 
00121   /**
00122    * Clear all data (generators, simulation attributes etc)
00123    *
00124    * This includes the "HardwareReset" event.
00125    *
00126    */
00127   virtual void Clear(void);
00128 
00129 
00130   /**
00131    * Execute event.
00132    *
00133    * Programmatically override any internal schedules and execute the specified event.
00134    * This routine will neither synchronize generator time nor events.
00135    *
00136    * @param event
00137    *   Event by index
00138    * @return 
00139    *   True on success
00140    */
00141   bool ExecuteEvent(Idx event);
00142     
00143 
00144   /** @} doxygen group */
00145 
00146   /** @name Application Interface */
00147   /** @{ doxygen group */
00148 
00149   /**
00150    * Set tolerance for time synchonisation.
00151    *
00152    * @param maxgap
00153    *   Max acceptable amount of faudes-time units by which the generators 
00154    *   global clock may be behind physical time
00155    *
00156    */
00157   void ToleranceTime(tpTime::Type maxgap) {mMaxSyncGap=maxgap; mSyncMode |= SyncStrictTime;};
00158 
00159   /**
00160    * Modes of synchronisation
00161    */
00162   typedef enum {
00163     SyncStrictTime   =0x01,
00164     SyncStrictEvents =0x02
00165   } SyncMode;     
00166 
00167   /**
00168    * Set synchronisation flags.
00169    *
00170    * Semantics are defined via the enum typedef SyncMode.
00171    *
00172    * @param flag
00173    *   Flag word to set mode
00174    *
00175    */
00176   void ToleranceMode(int flag) {mSyncMode=flag;};
00177 
00178   /**
00179    * Execute generator clock time to sync with device time.
00180    *
00181    * If possible, execute the amount of clock time required for an
00182    * exact match. Otherwise, accept the specified tolerance. As a
00183    * last resort, issue a sync error. 
00184    *
00185    * @return
00186    *   True, on success ie synchron within tolerance.
00187    */
00188   bool SyncTime(void);
00189 
00190   /**
00191    * Execute scheduled or sensor events now
00192    *
00193    * If an event is scheduled for now, execute it.
00194    * Otherwise, execute a sensor event if such is ready.
00195    * Otherwise execute do nothing.
00196    *
00197    * @return
00198    *   Idx of event executed, 0 for no execution or error
00199    */
00200   Idx SyncEvents();
00201 
00202 
00203   /**
00204    * Wait for sensor events
00205    *
00206    * Wait the specified amount of time, for the proposed time to elaps,
00207    * or a sensor event to occur - whatever comes first.
00208    * This function will *not* synchronise with generator time. You may 
00209    * call SyncTime afterwards.
00210    *
00211    * @param duration
00212    *   Max duration to wait for
00213    * @return
00214    *   True, if sensor events are available
00215    */
00216   bool SyncWait(tpTime::Type duration=tpTime::Max);
00217 
00218   /**
00219    * Wait for sensor events
00220    *
00221    * Wait the specified amount of time, for the proposed time to elaps,
00222    * or a sensor event to occur - whatever comes first.
00223    * This function will *not* synchronise with generator time. You may 
00224    * call SyncTime afterwards.
00225    * 
00226    * Note that the executor does not know about msecs, and thus the core interface
00227    * referc to faudes-time units only. This function is an exception of this rule
00228    * and is for convenience only.
00229    *
00230    * @param durationms
00231    *   Max duration in msecs to wait for
00232    * @return
00233    *   True, if sensor events are available
00234    */
00235   bool SyncWaitMs(int durationms);
00236 
00237   /**
00238    * Execute one transition with synchronous physical signals.
00239    *
00240    * Calls SyncTime, SyncEvents and SyncWait to execute one transition.
00241    * It will, however, not pass more than the specified duration. 
00242    *
00243    * @param duration
00244    *   Max duration of execution wrt generator time, tpTime::Max for unlimited
00245    * @return
00246    *   Idx of executed event or 0 for time out or error
00247    */
00248   Idx SyncStep(tpTime::Type duration=tpTime::Max);
00249 
00250   /**
00251    * Run execution with synchronous physical signals.
00252    *
00253    * Loops SyncStep until the specified amount on time expired.
00254    *
00255    * @param duration
00256    *   Duration of execution wrt generator time, tpTime::Max for infinite
00257    * @return
00258    *  True, for no error
00259    */
00260   bool SyncRun(tpTime::Type duration=tpTime::Max);
00261 
00262   /**
00263    * Test Syncronisation
00264    *
00265    * @return True, if device time and events are in sync with
00266    *   generator time and events.
00267    *
00268    */
00269   bool IsSynchronous(void) const { return ! mSyncError; };
00270 
00271   /**
00272    * Set device.
00273    *
00274    * The device must be configured. You must start
00275    * the device befor the first call to SyncRun. Ownership of 
00276    * the device stays with the caller.
00277    *
00278    * @param dev
00279    *   IO Device to use
00280    *
00281    */
00282   void Devicep(vDevice* dev);
00283 
00284   /**
00285    * Get device.
00286    *
00287    * Retturn a refernce to the device for inspection. Note: you must not
00288    * interfear with the device during synchronuous execution.
00289    *
00290    * @return dev
00291    *   IO Device to use
00292    *
00293    */
00294   vDevice* Devicep() { return pDevice; };
00295 
00296   /**
00297    * Convenience: Start the device.
00298    *
00299    */
00300   void DeviceStart(void);
00301 
00302   /**
00303    * Convenience: Stop the device.
00304    *
00305    */
00306   void DeviceStop(void);
00307 
00308   /** @} doxygen group */
00309 
00310  protected:
00311 
00312 
00313   /** Sync error flag */
00314   bool mSyncError;
00315 
00316   /** Max gap between physical and generator clock time  */
00317   tpTime::Type mMaxSyncGap;
00318  
00319   /** Mode flags for synchronisation */
00320   int mSyncMode;
00321  
00322   /** Device reference */
00323   vDevice* pDevice;
00324 
00325 
00326 
00327 }; // end class DeviceExecutor
00328 
00329 
00330 
00331 } // namespace faudes
00332 
00333 
00334 #endif // .h
00335 

libFAUDES 2.14g --- 2009-12-3 --- c++ source docu by doxygen 1.5.6