This class define the interface to provide a simulates system tick (in milliseconds) to the application.
More...
This class define the interface to provide a simulates system tick (in milliseconds) to the application.
The goal is provide a mechanism for an application to run in 'simulate time' instead of real time. The simulated tick mechanism is for the most part transparent an application, i.e. the application programmer does NOT have to be aware or design his code differently to be able to run in simulate tick mode. The 'intrusions points' are detailed below. The typical uses cases for using simulated time are:
o Testing. A simulated system tick allows the test harness to have
deterministic control of the application's time. In addition, time
can be singled stepped, paused, accelerated (i.e. run N days in
M minutes).
o Model in the Loop (MIL). An external application such as Matlab/
Simulink can be used to provide the simulated tick input as well
as capture the application's output and provide the application
inputs, i.e. connecting the application to a simulated physical
world. Note: 'connecting' a MIL application to a simulation such
as Matlib/Simulink requires a communication layer that is NOT
provided by Colony as well as specialization to Matlib/Simulink
that mates up with the afore mentioned communication layer. This
is left as an exercise to the reader :).
NOTES:
------
o All timing sources, e.g. Cpl::Api::sleep(), provided by Colony.Core
have support for simulated ticks build in.
o All of the Colony.Core's ITC message queues/mailbox servers, etc. also
have support for simulated ticks build in.
o With respect to threads that are using simulated time, There needs to
be at least one thread (at any given time) that is a 'timing' source,
e.g. waiting on sleep(), timedWait(), etc. If your application uses
a Cpl::System::EventLoop (or a sub-class) instance - then this
requirement has been met. Worse case you a create a thread that
forever loops on sleep().
o This interface is independent of the underlaying platform, i.e works
on ALL platforms.
o NOT all threads and/or parts of an application need or should use
simulated time. For example the test harness (or communication
interface to a simulation tool) that provide the stimulus to
advance the simulated tick need to run in real-time. It is the
Application responsibility to properly selected what is and is
not using simulated time.
- The platform's native/main thread ALWAYS runs in 'real-time', i.e.
call to SimTick::wait() never blocks. Also any Api::sleep()
calls from the native/main thread are redirected to the
Api::sleepInRealTime().
o THREADING: This interface provides ONLY a functional simulation of
system ticks. These means the actual runtime timing of threads and/or
sequence of execution will NOT be the same as the 'live'
non-simulated application.
- When using simulated ticks with multi-threaded applications, the
timing of the threads using the simulated ticks behavior is 'better'
if the thread supplying the ticks has LOWER priority than the
threads using the simulate ticks.
- BEWARE of multi-core targets. Because many threads can actually
execute at the SAME time on multi-core boxes, the timing between
the tick source thread and the simulated-tick threads and between
simulated-tick threads is UNPREDICTABLE. The tick sequencing
is guaranteed, but the order within a tick OR timing relations to
the tick source OR inter-tick timing is NOT guaranteed.
- Not all use cases using a simulated tick and threading will work
and/or are supported. The simulated tick logic only works for
event driven and/or frequency based where all actions for a time
period as completed in on pass of the "main loop". Other issues:
o The assumption is that all calls to a mutex will cause the
thread to block across simulated ticks, i.e. mutex can ALWAYS
be successfully acquired and release within the context of
single simulated tick
- Be careful about deleting threads when using Simulated Ticks -
brute force terminating threads in this scenario has unpredictable
and/or improper behavior. Always have threads run to completion
when using Simulate Ticks.
o The DEFAULT implementation of this interface assumes that one
system tick EQUALS one millisecond.
HOW TO ADD SIMULATED TICK SUPPORT
---------------------------------
o Enabling Simulated time is done at compile done. The following steps
are required:
1) Compile with the preprocessor symbol USE_CPL_SYSTEM_SIM_TICK
defined.
2) Compile & Link the src/Cpl/System/_simtick directory. Also do NOT
compile/link the src/Cpl/System/xxx/_realtime directories
o Typically thats all that needs to be done. The only additional work is if
application creates thread(s) that have an application specific (i.e. not
a Colony.Core Event Loop, mailbox server, etc.) 'forever' loop AND it
is desired for the thread(s) to use 'simulated time'. For this scenario
the application must add a call to this interface at the top of the
forever loop. See the example below:
void myThreadEntryFunction( void* arg )
{
...
while(1)
{
// Block the main loop until the next simulated system tick
CPL_SYSTEM_SIM_TICK_TOP_LEVEL_WAIT();
...
}
}
}
|
| static void | topLevelWait (void) noexcept |
| | This method will cause the current thread to block UNTIL one simulated system tick has elapsed.
|
| |
| static bool | usingSimTicks (void) noexcept |
| | This method returns true if the current thread is using 'simulated time'.
|
| |
| static void | applicationWait (void) noexcept |
| | This method is used to support blocking calls (such as wait on semaphore, sleep(), etc.) within an individual iteration of thread's top level loop.
|
| |
| static size_t | current (void) noexcept |
| | This method returns the current simulated tick count.
|
| |
| static bool | advance (size_t numTicks) noexcept |
| | Calling this method advances the application's time by 'numTicks'.
|
| |
| static bool | isWaitingOnNextTick (size_t threadID) noexcept |
| | This method returns true if the specified thread (by Thread ID) is blocked waiting on the next simulate tick.
|
| |
| static void | threadInit_ (bool useSimTicks=true) noexcept |
| | This COMPONENT Scoped method is used during thread creation to insert the necessary hooks (per thread) for the simulate tick engine.
|
| |
| static void | onThreadExit_ (void) noexcept |
| | This COMPONENT Scoped method is used during thread deletion to insert the necessary hooks (per thread) for the simulate tick engine.
|
| |
| static void | remove_ (Item *itemPtr) noexcept |
| | Helper method to do the proper 'clean-up' for the multiple-containers-error-trap when removing an item from a container.
|
| |
Static Public Member Functions inherited from Cpl::Container::Item
1.9.8