/*!

\page timingservice TimingService documentation

<hr>

\section timing_service_purposes Purposes of IDEA Timing Services

There are a number of high-level requirements for the Timing Services executable which is part of the IDEA Core.  This executable (TS):  
\li Provides coordination of time keeping (and other time-related services) among a system of IDEA agents such that all participating agents have a 
single notion of time.  In such a system, one or more agents running on the same machine will (must) use a single Timing Services provider.
\li In simulation mode, TS allows IDEA to bypass (i.e., eliminate) certain time intervals where it can be determined in advance that no commanding 
activity will need to be simulated.  In this case it is possible to shorten the overall simulation timeline such that a common time translation, 
called warping, occurs for all the agents subscribing to the given timing service.  Simply put, warping is used to skip over uninteresting/unneeded 
intervals in a simulation.  If this operation is permitted, it is carried out automatically by the software.
\li The timing service must be able to determine precisely when, in the future, it is possible to warp.
\li Provides a facility allowing agents to  query and obtain the current time.
\li The pivot date, that is, the reference epoch used by a given timing service, must be a configurable parameter.  The pivot date is also referred 
to as the epoch time or base time.
\li At least two agents (currently the capacity is 16) must be able to connect to (subscribe to) a single timing service.
\li Any agent must be able to send a message to the timing service requesting that a message be returned to it (the agent) at a specific future time.  
This is referred to as a wake-up call request.

<hr>

\section current_timing_services_implementation Current Implementation of Timing Services

\li Uses shared memory on a single machine.  Shared memory is an operating system service that allows more than one processor to have access to the 
same portion of a machines memory.  This area of memory is called a memory pool.
\li Agents are currently limited to run on the same machine as the timing services they subscribe to.
\li The purpose of using shared memory is to obtain high speed communications among agents and timing services.
\li Timing services uses the operating system services of named process semaphores and mutexes

The following subsections describe basic timing service functions:

\subsection wake_up_requests  Timing Service Wake Up Requests

\li Processes are allowed to write wake up requests into a specific area of the shared memory pool; each request consists of that processes name 
and a future time when that process requires a message to be sent to it, so that that process can perform some function at that exact time.
\li TS constantly interrogates the memory pool to determine when sending a message to any given Agent is required.  When the time specified by that 
Agent is reached, TS releases a named process semaphore to that process; in this way, TS wakes up the process at time it has requested.  Finally, 
at this point, TS releases the shared memory which had been used to store that processes request.
 

\subsection time_scaling Time Scaling 

Time scaling is used to stretch out simulated time, so that it is slower than wall-clock time.  For example, one second of real time becomes  second 
of simulated time and (in this example)  in ten seconds of wall-clock time, only five seconds of simulated commands will be processed.

\subsection warping Warping

\li Warping, as already described, is the coordinated elimination of an interval in simulated time for all subscribing Agents simultaneously. 
\li Timing Services will initiate warping whenever it is permitted.  However, there are four separate requirements that must be satisfied before warping 
can occur.  The TS is constantly checking to determine if these conditions are met.
\li Warping must be enabled.  Warping is enabled by use of a command line option; see below.
\li No future activity can be scheduled to start within the candidate warping time interval.  In order to eliminate this possibility, TS examines all 
of the requests for activity start-ups (i.e., wake-up calls) which processes have entered earlier into the TS shared memory pool.  The earliest such 
start-up time will determine the end of the potential warp interval.
\li . In addition, there are two counters maintained in shared memory  which control the warping process.  The first is a command counter, which counts 
the number of executing commands (specifically those which require CPU) for all of the subscribing agents together, and a second counter which counts the 
number of messages currently at large in the agent system; called the message counter.
\li  The use of the command counter:  Warping cannot be initiated if any command is currently executing which uses CPU.   If such a command is executing, 
it is possible that it may continue to execute beyond the padding safety time (see below), and thus within the potential warping time interval.  Such a 
condition is prevented by examining the end times of all of the current tokens on each timeline.  It is safe to warp after the latest such end time, 
because at that time all of the current tokens will have ceased execution.  The command counter is used as follows:  when any command requiring CPU begins 
execution, a command counter in shared memory is incremented.  When any such command ends, the same shared-memory counter is decremented.  Thread integrity 
(between the Agent and TS) for this counter is maintained by the use of mutexes in the incrementing/decrementing process:  the process in question locks 
the shared memory via a mutex, increments or decrements the counter, and then releases the mutex.  Note:  ehen the command counter is adjusted, the process 
also increments (or as appropriate, decrements) the message counter described below, also using mutexes.
\li Use of the message counter.  In addition to establishing that there are no CPU-utilizing commands executing, initiation of warping requires that no 
inter-process messages are currently unhandled (that is, either on the way or waiting to be processed).  To eliminate this possibility, the Agent Relay 
for each agent maintains (with other Agents Agent Relays) a second counter, also in shared memory, which keeps a count of all messages initiated by that 
Agent.  This counter is  then decremented when any message is processed.  Mutexes are used to protect thread integrity for this counter as well.
\li Since commands are also counted in the message counter, the message counter is always the larger counter in this arrangement.  When the TS determines 
that the message counter has (just) decremented to 0, it initiates warping if all other required conditions are met.  This means that if warping is enabled, and conditions permit it, it is initiated automatically by timing services.
\li   The final conditions required for warping are governed by an additional two command line parameters.  These are:
\li Minimum warp time  the minimum time useful to warp.  If the requested warp interval is smaller than this minimum, TS will not initiate the warping 
action.  The minimum warp is currently set at 4 seconds.
\li Warping pad:  A time interval subtracted from the start of the warping time interval, such that warping does not occur until after the pad.  The pad 
provides a safety margin for the activities described above.   The current pad is currently set at 4 seconds.  This can probably be reduced.  

\section TS_command_line_parameters TS Command Line Parameters

TS is built as a separate executable, within the IDEA-DEV module.  This executable has seven command line parameters (an eighth, -h, invokes the TS help facility, which lists the other parameters). These seven command line parameters are:

\li Time Scale
\li  Pool name (used to inform subscribing Agent(s) the designated area of shared memory which it (they) will share with TS
\li  Time offset
\li  Pivot Time
\li  Warping enable/disable flag
\li  Minimum Warping Time
\li  Warping Pad

*/
