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

libFAUDES 2.33a --- 2025.05.02 --- c++ api documentaion by doxygen