OMK::Clock Class Reference

A clock to synchronize the time in simulation. More...

#include <OMKClock.h>

Inheritance diagram for OMK::Clock:

[legend]Collaboration diagram for OMK::Clock:

[legend]List of all members.

Public Member Functions
	DECLARE_OBJECT_FACTORY (Clock)
OpenMask inherited methods
virtual void	init ()
	Init method inherited from SimulatedObject.
virtual void	compute ()
	Compute method inherited from SimulatedObject.
virtual bool	processEvent (Event *event)
	process an event for this object.
class methods
bool	isSleepActive () const
	Get the clock active or passive sleep mode.
void	setSleepActive (bool activeSleep)
	Set the clock active sleep mode.
bool	isFreeRunning () const
	Get the clock in free run or controled mode.
void	setFreeRunning (bool freeRun)
	Set the clock active sleep mode.
float	getRealMultiplier () const
	Get the real clock ratio.
float	getWantedMultiplier () const
	Get the wanted clock ratio.
void	setWantedMultiplier (float m)
	Set the wanted clock ratio.
Protected Attributes
unsigned long	_lastCallDate
	Last call date to compute in micro-secondes.
unsigned long	_lastRealRefresh
	To regularly update simulated clock and ratio display.
unsigned long	_firstRealDate
	Store the first date in secondes to calculate the elapsed real time Negative: time to catch up: time to spend.
long	_timeToSpend
	Time during compute loop in micro-secondes.
unsigned long	_simulFrequency
	Store frequency to avoid a call to object parameters.
float	_wantedMult
	Wanted ratio between real time and simulated time.
float	_realMult
	Real ratio between real time and simulated time. See Configuration parameters.
bool	_freeRun
	Set to true if in free run mode.
bool	_activeSleep
	The sleep mode.
bool	_simulationStarted

---

Detailed Description

A clock to synchronize the time in simulation.

Author:

S�astien PARIS (& Beno� CHANCLOU ) (& Julien Bilavarn)

Date:

2005-05-31

Author:

Xavier Larrod�: base Clock on ExtensibleSimulatedObject for OMK 4.0

OpenMask version :

4.0

Module description :

This simulated object allows to constraint the simulation to a given speed ratio ("1" means real time is equal to simulated time, "2" means real time is equal to half of the simulated time, or the simulation runs twice faster than the real time).

The only thing to do is to add this simulated object to your simulation. The clock spend time to synchronize with the good ratio with the real time. You have to choose the frequency according to the object you want to control. Keep in mind that the clock waits each time its compute is called, so a too high frequency creates a performance issue.

Visualisable module :

no configurationParameters All the parameters have a default value (between parentheses), be careful with short keys.

• InitCoeff : float (1.0 like real time)
• FreeRun : bool (false)
• SleepProcedure : "active" | "passive" ("active")

Example of configuration file

 clock
 {
   Class Clock
   Scheduling
   {
     Frequency 75
   }
   UserParams
   {
           FreeRun          FALSE
           SleepProcedure   ACTIVE
     InitCoeff        1.0
   }
 }

Definition at line 76 of file OMKClock.h.

---

Member Function Documentation

OMK::Clock::DECLARE_OBJECT_FACTORY

(

Clock

)

void Clock::init

(

)

[virtual]

Init method inherited from SimulatedObject.

Calls the loaders.
Most of the time it is not necessary to redefine this method in the children class. If you have to add some initialisations, redefine and call the inherited method to load parameters or call directly the loaders.

Reimplemented from OMK::ExtensibleSimulatedObject.

Definition at line 70 of file OMKClock.cpp.

References _activeSleep, _firstRealDate, _freeRun, _lastCallDate, _lastRealRefresh, _simulFrequency, _wantedMult, OMK::ParametersAccessor::get(), OMK::SimulatedObject::getConfigurationParameters(), OMK::ObjectDescriptor::getFrequency(), OMK::SimulatedObject::getObjectDescriptor(), OMK::ExtensibleSimulatedObject::init(), and setWantedMultiplier().

{
  const ConfigurationParameterDescriptor* prm = getConfigurationParameters();
  
  std::string str;
  if( ParametersAccessor::get( prm, "SleepProcedure", str ) )
  {  
    std::transform( str.begin(), str.end(), str.begin(), toupper );
    _activeSleep = !( str == "PASSIVE" );
  }

  ParametersAccessor::get( prm, "FreeRun"     , _freeRun      );
  ParametersAccessor::get( prm, "InitCoeff"   , _wantedMult   );
  setWantedMultiplier( _wantedMult ) ;

#ifdef _MSC_VER
  QueryPerformanceCounter( &_startSimulationDate ) ;
  _lastRealRefresh = _startSimulationDate ;
  _lastCallDate = _startSimulationDate ;
#else
  timeval currentTime;
  gettimeofday( &currentTime, NULL );
  _firstRealDate = currentTime.tv_sec;
  // The filter is used to avoid numeric overflow
  _lastRealRefresh = _lastCallDate = ( currentTime.tv_sec & 0xfff ) * 1000000 + currentTime.tv_usec;
#endif

  _simulFrequency = getObjectDescriptor().getFrequency();
  return ExtensibleSimulatedObject::init();
}

void Clock::compute

(

)

[virtual]

Compute method inherited from SimulatedObject.

The compute method is splitted in three main parts:

• the first reads the inputs,
• the second computes the new values for the parameters,
• the last one sets the outputs from their associated parameters.

The second method computeParameters is a pure virtual method and must be defined in the child classes.
The inputs and outputs should work with associated data, you should use these associated data.

The extensions take place between each step :

• preComputeParameters takes place between the first two steps.
• postComputeParameters takes place between the last two steps.

So the extensions could modify the associated data, after they have been retrieved in the inputs, and before they have been copied in the outputs.

See Computing of simulated object for more details.

Reimplemented from OMK::ExtensibleSimulatedObject.

Definition at line 110 of file OMKClock.cpp.

References _activeSleep, _freeRun, _lastCallDate, _realMult, _simulationStarted, _simulFrequency, _timeToSpend, _wantedMult, and OMK::ExtensibleSimulatedObject::compute().

{
        if(!_simulationStarted){
          _simulationStarted = true ;
#ifdef _MSC_VER
          // current time in micro-sec
          LARGE_INTEGER firstDate ;
          QueryPerformanceCounter( &firstDate ) ;
          _startSimulationDate = firstDate ;
          _lastCallDate = firstDate ;
#else
          timeval firstTime;
          gettimeofday( &firstTime, NULL );
          // current time in micro-sec
          _lastCallDate = ( firstTime.tv_sec & 0xfff ) * 1000000 + firstTime.tv_usec;
#endif
        }

#ifdef _MSC_VER
  // current time in micro-sec
  LARGE_INTEGER newCallDate ;
  QueryPerformanceCounter( &newCallDate ) ;
  LARGE_INTEGER currentDate = newCallDate ;
  // ratio of step duration by elapsed time since last call
  _realMult = (float)( ( 1/ _simulFrequency ) * (_processorFrequency.QuadPart / (newCallDate.QuadPart - _lastCallDate.QuadPart) ) ) ;
#else
  timeval currentTime;
  gettimeofday( &currentTime, NULL );
  // current time in micro-sec
  unsigned long newCallDate = ( currentTime.tv_sec & 0xfff ) * 1000000 + currentTime.tv_usec;
  // ratio of step duration by elapsed time since last call
  _realMult = ( 1000000.0f / _simulFrequency ) / ( newCallDate - _lastCallDate );
#endif

  if( _freeRun )
  {
    _timeToSpend = 0;
  }
  else
  {  
    // Controled time, sleep if necessary
    // step duration in micro-sec
    long stepDuration = (long)( 1000000.0f / ( _simulFrequency * _wantedMult ) );
    // sleep duration is the wanted step duration minus the time needed for simulation
    // negative: time to catch up, positive: time to spend
#ifdef _MSC_VER
        _timeToSpend += (long)( stepDuration + ((_lastCallDate.QuadPart - newCallDate.QuadPart)*1000000/_processorFrequency.QuadPart) ) ;
#else
    _timeToSpend += _lastCallDate - newCallDate + stepDuration ;
#endif
    // never sleep more than step duration (to avoid numeric overflow on signed long)
    _timeToSpend = (stepDuration < _timeToSpend) ? stepDuration : _timeToSpend ;
    
    if( 0 < _timeToSpend )
    { 
      // Some time to spend
      if( _activeSleep )
      { 
        // Active sleep => loop
#ifdef _MSC_VER

                long currentStep = 0 ;
                while( currentStep < _timeToSpend){
                        QueryPerformanceCounter( &currentDate ) ;
                        currentStep = (long)(( currentDate.QuadPart - newCallDate.QuadPart )*1000000/_processorFrequency.QuadPart); // Get step in micro-sec

                }
#else
        // Compute the date to reach with the dummy loop
        timeval targetDate;
        targetDate.tv_sec = currentTime.tv_sec ;
        targetDate.tv_usec = currentTime.tv_usec + _timeToSpend ;
        for( targetDate.tv_usec = currentTime.tv_usec + _timeToSpend ; 
             1000000l < targetDate.tv_usec ; 
             targetDate.tv_usec -= 1000000l )
        { // Add a seconde until targetDate.tv_usec is in range (< 10000000usec)
          targetDate.tv_sec++ ;
        }

        while( currentTime.tv_sec < targetDate.tv_sec
            || ( currentTime.tv_sec == targetDate.tv_sec
               && currentTime.tv_usec < targetDate.tv_usec ) )
        { // The dummy loop until date is reached
            gettimeofday( &currentTime, NULL );
        }
#endif

      } 
      else
      { 
        // Passive sleep => nanosleep call
#ifdef _MSC_VER
        // TODO / FIX Windows "Sleep" is not precise enough (~10ms), and current method is :
            // 1. First, make PASSIVE SLEEP as much as possible (milli-second granularity)
        Sleep(_timeToSpend/1000);
                // 2. Then, spend the rest of time with active sleep
                long currentStep = (long)(( currentDate.QuadPart - newCallDate.QuadPart )*1000000/_processorFrequency.QuadPart ) ; // Get step in micro-sec
                while( currentStep < _timeToSpend){
                        QueryPerformanceCounter( &currentDate ) ;
                        currentStep = (long)( ( currentDate.QuadPart - newCallDate.QuadPart )*1000000/_processorFrequency.QuadPart ) ; // Get step in micro-sec
                }
#else
                timespec sleepNanoTime;
        sleepNanoTime.tv_sec = 0;
        sleepNanoTime.tv_nsec = _timeToSpend * 1000l ;
        nanosleep( &sleepNanoTime, NULL );
#endif
      }
    }
  }
  // store the call date for next call
  _lastCallDate = newCallDate;

  ExtensibleSimulatedObject::compute();
}

bool Clock::processEvent

(

Event *

event

)

[virtual]

process an event for this object.

the event will be automatically deleted if the return value of the call is true, otherwise deletion becomes the responsability of the object

Reimplemented from OMK::SimulatedObject.

Definition at line 103 of file OMKClock.cpp.

References OMK::SimulatedObject::processEvent().

{
  return ExtensibleSimulatedObject::processEvent( event ) ;
}

bool OMK::Clock::isSleepActive

(

)

const [inline]

Get the clock active or passive sleep mode.

Returns:

true if the clock is in active sleep mode,
false if the clock is in passive sleep mode.

Definition at line 94 of file OMKClock.h.

{ return _activeSleep ; }

void OMK::Clock::setSleepActive

(

bool

activeSleep

)

[inline]

Set the clock active sleep mode.

Parameters:

[in]

activeSleep

if true the clock is set in active sleep mode, if false the clock is set in passive sleep mode.

This property can be set with SleepProcedure parameter. See Configuration parameters.

Definition at line 101 of file OMKClock.h.

{ _activeSleep = activeSleep ; }

bool OMK::Clock::isFreeRunning

(

)

const [inline]

Get the clock in free run or controled mode.

Returns:

true if the clock is in free run mode,
false if the clock is in controled mode.

Definition at line 106 of file OMKClock.h.

{ return _freeRun; }

void OMK::Clock::setFreeRunning

(

bool

freeRun

)

[inline]

Set the clock active sleep mode.

Parameters:

[in]

freeRun

if true the clock is set in free run mode, if false the clock is set in controled mode.

This property can be set with FreeRun parameter. See Configuration parameters.

Definition at line 113 of file OMKClock.h.

  {  
    _freeRun = freeRun;
  }

float OMK::Clock::getRealMultiplier

(

)

const [inline]

Get the real clock ratio.

Returns:

the real ratio between simulated time and real time.

Definition at line 120 of file OMKClock.h.

{ return _realMult; }

float OMK::Clock::getWantedMultiplier

(

)

const [inline]

Get the wanted clock ratio.

Returns:

the wanted ratio between simulated time and real time.

Definition at line 124 of file OMKClock.h.

{ return _wantedMult; }

void OMK::Clock::setWantedMultiplier

(

float

m

)

[inline]

Set the wanted clock ratio.

Parameters:

[in]

m

is the wanted ratio between simulated time and real time.

This property can be set with InitCoeff parameter. See Configuration parameters.

Definition at line 130 of file OMKClock.h.

Referenced by init().

{ if( 0 < m ) _wantedMult = m; }

---

Member Data Documentation

unsigned long OMK::Clock::_lastCallDate [protected]

Last call date to compute in micro-secondes.

Definition at line 140 of file OMKClock.h.

Referenced by compute(), and init().

unsigned long OMK::Clock::_lastRealRefresh [protected]

To regularly update simulated clock and ratio display.

Definition at line 141 of file OMKClock.h.

Referenced by init().

unsigned long OMK::Clock::_firstRealDate [protected]

Store the first date in secondes to calculate the elapsed real time Negative: time to catch up: time to spend.

Definition at line 143 of file OMKClock.h.

Referenced by init().

long OMK::Clock::_timeToSpend [protected]

Time during compute loop in micro-secondes.

Definition at line 145 of file OMKClock.h.

Referenced by compute().

unsigned long OMK::Clock::_simulFrequency [protected]

Store frequency to avoid a call to object parameters.

Definition at line 146 of file OMKClock.h.

Referenced by compute(), and init().

float OMK::Clock::_wantedMult [protected]

Wanted ratio between real time and simulated time.

This property can be set with InitCoeff parameter.

Definition at line 148 of file OMKClock.h.

Referenced by compute(), and init().

float OMK::Clock::_realMult [protected]

Real ratio between real time and simulated time. See Configuration parameters.

Definition at line 150 of file OMKClock.h.

Referenced by compute().

bool OMK::Clock::_freeRun [protected]

Set to true if in free run mode.

This property can be set with FreeRun parameter. See Configuration parameters.

Definition at line 152 of file OMKClock.h.

Referenced by compute(), and init().

bool OMK::Clock::_activeSleep [protected]

The sleep mode.

This property can be set with SleepProcedure parameter. See Configuration parameters.

Definition at line 155 of file OMKClock.h.

Referenced by compute(), and init().

bool OMK::Clock::_simulationStarted [protected]

Definition at line 158 of file OMKClock.h.

Referenced by compute().

---