sp_dplpexecutor.h
Go to the documentation of this file.
1 /** @file sp_dplpexecutor.h Executor with IO device */
2 
3 /*
4  FAU Discrete Event Systems Library (libfaudes)
5 
6  Copyright (C) 2008 Thomas Moor
7 
8 */
9 
10 // load configuration
11 #include "corefaudes.h"
12 
13 #ifndef FAUDES_SP_DPLPEXECUTOR_H
14 #define FAUDES_SP_DPLPEXECUTOR_H
15 
16 
17 #include "tp_include.h"
18 #include "sp_plpexecutor.h"
19 #include "sp_simeventset.h"
20 #include <ctime>
21 
22 
23 // use iodevice or dummy if not available
24 #ifdef FAUDES_PLUGIN_IODEVICE
25 #include "iop_include.h"
26 #else
27 namespace faudes {
28 /** Dummy typedef in the absence of the IO Device plugin */
29 typedef void vDevice;
30 }
31 #endif
32 
33 namespace faudes {
34 
35 /**
36  * Executer with IO device to handle external/physical events
37  *
38  * \section SecSimulatorDPLPEX1 External/Physical Events and Time
39  *
40  * This executor class is derived from the ProposingExecutor and uses a vDevice
41  * from the IO Device Plugin to handle input and output events and physical time.
42  * Technically, the class provides the routine SyncStep() that has to be called periodically to
43  * synchronize executor clock time with physical time and to perform input readings and
44  * output writings. There is also a convenience routine SyncRun() which runs a loop
45  * with SyncStep().
46  *
47  * The SyncStep() procedure implements the below stages. It returns true, if indeed
48  * a transition was executed. It returns false on synchronistion errors or when the specified
49  * duration expired.
50  *
51  * - get a proposal from ProposingEcexutor
52  * - if physical time is ahead of the genartors current clock time, sync time by
53  * ExecuteTime; in the case that this is not consistent with the proposal,
54  * an error is reported;
55  * - if the generators current clock time is ahead of physical time, an error is reported
56  * - if a input event has been reported that can be executed at generators current time, execute it
57  * - if the proposal schedules an event for the generators current time, execute it
58  * - if a input event has been reported, execute it now; if this event is not accepted by the generator, report an error
59  * - if the proposals time is not yet executed, wait for that amount of time to pass
60  * or a input event to be delivered.
61  *
62  *
63  *
64  * Naturally, the DeviceExecutor requires the IO Device plugin in order to be functional.
65  * In the absence of the plugin, the DeviceExecutor will behave like a ProposingExecutor.
66  *
67  * \section SecSimulatorLPEX3 File IO
68  *
69  * The DeviceExecutor inherits file IO from the ProposingExecutor. The device itself
70  * is initialized by vDevice methods (eg configured from File) and then passed to the
71  * DeviceExecutor by the method Devicep(). Thus, the DeviceExecutor does not need to
72  * implement additional token io facilities.
73  *
74  * @ingroup SimulatorPlugin
75  */
76 
78 
80 
81  public:
82 
83  /*****************************************
84  *****************************************
85  *****************************************
86  *****************************************/
87 
88  /** @name Constructors & Destructor */
89  /** @{ doxygen group */
90 
91  /**
92  * Creates an emtpy DeviceExecutor
93  */
95 
96  /**
97  * Copy constructor
98  */
100 
101  /**
102  * Explicit destructor
103  */
104  ~DeviceExecutor();
105 
106 
107  /**
108  * Dummy factory method.
109  *
110  * Note: the executor classes currently do not implement
111  * faudes Type RTI related function. This factory method
112  * is only to prevent registry error messages.
113  */
114  DeviceExecutor* New(void) { return new DeviceExecutor();};
115 
116 
117  /** @} doxygen group */
118 
119  /*****************************************
120  *****************************************
121  *****************************************
122  *****************************************/
123 
124  /** @name Re-implemenented from ParallelExecutor */
125  /** @{ doxygen group */
126 
127  /**
128  * Reset the DeviceExecutor.
129  *
130  * Reset the executor to its initial state and reset the device, ie clear queued
131  * input event set outputs to a passive state
132  *
133  * @param seed
134  * Seed for PropossingExecutor random generator, 0<>system time
135  */
136  virtual void Reset(long int seed=0);
137 
138  /**
139  * Clear all data (generators, simulation attributes etc)
140  *
141  * This includes the "HardwareReset" event.
142  *
143  */
144  virtual void Clear(void);
145 
146 
147  /**
148  * Execute event.
149  *
150  * Programmatically override any internal schedules and execute the specified event.
151  * This routine will neither synchronize generator time nor events.
152  *
153  * @param event
154  * Event by index
155  * @return
156  * True on success
157  */
158  bool ExecuteEvent(Idx event);
159 
160 
161  /** @} doxygen group */
162 
163  /** @name Application Interface */
164  /** @{ doxygen group */
165 
166  /**
167  * Set tolerance for time synchonisation.
168  *
169  * @param maxgap
170  * Max acceptable amount of faudes-time units by which the generators
171  * global clock may be behind physical time
172  *
173  */
175 
176  /**
177  * Modes of synchronisation
178  */
179  typedef enum {
182  } SyncMode;
183 
184  /**
185  * Set synchronisation flags.
186  *
187  * Semantics are defined via the enum typedef SyncMode.
188  *
189  * @param flag
190  * Flag word to set mode
191  *
192  */
193  void ToleranceMode(int flag) {mSyncMode=flag;};
194 
195  /**
196  * Execute generator clock time to sync with device time.
197  *
198  * If possible, execute the amount of clock time required for an
199  * exact match. Otherwise, accept the specified tolerance. As a
200  * last resort, issue a sync error.
201  *
202  * @return
203  * True, on success ie synchron within tolerance.
204  */
205  bool SyncTime(void);
206 
207  /**
208  * Execute scheduled or input events now
209  *
210  * If an event is scheduled for now, execute it.
211  * Otherwise, execute a input event if such is ready.
212  * Otherwise execute do nothing.
213  *
214  * @return
215  * Idx of event executed, 0 for no execution or error
216  */
217  Idx SyncEvents();
218 
219 
220  /**
221  * Wait for input events
222  *
223  * Wait the specified amount of time, for the proposed time to elaps,
224  * or a input event to occur - whatever comes first.
225  * This function will *not* synchronise with generator time. You may
226  * call SyncTime afterwards.
227  *
228  * @param duration
229  * Max duration to wait for
230  * @return
231  * True, if input events are available
232  */
233  bool SyncWait(tpTime::Type duration=tpTime::Max);
234 
235  /**
236  * Wait for input events
237  *
238  * Wait the specified amount of time, for the proposed time to elaps,
239  * or a input event to occur - whatever comes first.
240  * This function will *not* synchronise with generator time. You may
241  * call SyncTime afterwards.
242  *
243  * Note that the executor does not know about msecs, and thus the core interface
244  * referc to faudes-time units only. This function is an exception of this rule
245  * and is for convenience only.
246  *
247  * @param durationms
248  * Max duration in msecs to wait for
249  * @return
250  * True, if input events are available
251  */
252  bool SyncWaitMs(int durationms);
253 
254  /**
255  * Execute one transition with synchronous physical signals.
256  *
257  * Calls SyncTime, SyncEvents and SyncWait to execute one transition.
258  * It will, however, not pass more than the specified duration.
259  *
260  * @param duration
261  * Max duration of execution wrt generator time, tpTime::Max for unlimited
262  * @return
263  * Idx of executed event or 0 for time out or error
264  */
266 
267  /**
268  * Run execution with synchronous physical signals.
269  *
270  * Loops SyncStep until the specified amount on time expired.
271  *
272  * @param duration
273  * Duration of execution wrt generator time, tpTime::Max for infinite
274  * @return
275  * True, for no error
276  */
277  bool SyncRun(tpTime::Type duration=tpTime::Max);
278 
279  /**
280  * Test Syncronisation
281  *
282  * @return True, if device time and events are in sync with
283  * generator time and events.
284  *
285  */
286  bool IsSynchronous(void) const { return ! mSyncError; };
287 
288  /**
289  * Set device.
290  *
291  * The device must be configured. You must start
292  * the device befor the first call to SyncRun. Ownership of
293  * the device stays with the caller.
294  *
295  * @param dev
296  * IO Device to use
297  *
298  */
299  void Devicep(vDevice* dev);
300 
301  /**
302  * Get device.
303  *
304  * Retturn a refernce to the device for inspection. Note: you must not
305  * interfear with the device during synchronuous execution.
306  *
307  * @return dev
308  * IO Device to use
309  *
310  */
311  vDevice* Devicep() { return pDevice; };
312 
313  /**
314  * Convenience: Reset the device.
315  *
316  */
317  void DeviceReset(void);
318 
319  /**
320  * Convenience: Start the device.
321  *
322  */
323  void DeviceStart(void);
324 
325  /**
326  * Convenience: Stop the device.
327  *
328  */
329  void DeviceStop(void);
330 
331  /**
332  * Query the device whther it has received an external reset request.
333  * This method will reset the request.
334  *
335  * @return
336  * True, if there is such a reset request
337  */
338  virtual bool DeviceResetRequest(void);
339 
340  /** @} doxygen group */
341 
342  protected:
343 
344 
345  /** Sync error flag */
347 
348  /** Max gap between physical and generator clock time */
350 
351  /** Mode flags for synchronisation */
353 
354  /** Device reference */
356 
357  /**
358  * Assignment method
359  *
360  * @param rSrc
361  * Source to assign from
362  */
363  virtual void DoAssign(const DeviceExecutor& rSrc);
364 
365 
366 
367 }; // end class DeviceExecutor
368 
369 
370 
371 } // namespace faudes
372 
373 
374 #endif // .h
375 

libFAUDES 2.24g --- 2014.09.15 --- c++ api documentaion by doxygen