Madara Wiki

Middleware for distributed applications

Brought to you by: jredmondson

Time

MADARA has many different time mechanisms and quality-of-service mechanisms that refer to or manage time-based events or actions. In this wiki page, we'll try to discuss mechanisms available to developers concerning management, control, recording, and reacting to time.

Time Utilities

ACE: Everything available in ACE including nanosecond timers, durations, timestamps, portable wallclock time, etc. is fully supported in MADARA. ACE is a prerequisite, so you inherit all of the portable OS time utilities from there.

An example usage of ACE time for nanosecond resolution timers and durations can be seen in the following:

#include "ace/High_Res_Timer.h"

// ACE timer and nanosecond duration
ACE_High_Res_Timer timer;
ACE_hrtime_t duration;

// start the timer, do some work, stop the timer.
timer.start ();
...
timer.stop ();

// calculate duration in nanoseconds. Can also convert from the duration to an ACE_Time_Value
timer.elapsed_time (duration);

Similarly, developers can use time (NULL) or any other standard time keeping mechanism and put the result of such operations inside of the knowledge base for later retrieval and usage.

MADARA also provides standard get time and sleep related functions, including:

Sleep: madara::utility::sleep (double seconds): hard sleep that ignores OS interrupts and guarantees a sleep as long as the time specified in wall clock time.
Sleep: madara::utility::sleep (ACE_Time_Value): hard sleep that ignores OS interrupts and guarantees a sleep as long as the time specified in ACE Time Value format (lots of options for specifying in nanoseconds, microseconds, milliseconds, etc.)
Timestamp: madara::utility::get_time (void): returns time of day in nanoseconds (useful for duration timestamps).

MADARA has time system calls inside of the KaRL scripting language: Full List of System Calls

#get_clock () or #get_clock (variable):
  Returns either the system clock or the variable clock. Note that
  this is a Lamport clock value and not a wall time value.

#get_time () or #get_time_ns() or #get_time_nano():
  Returns wall clock time on the local machine in nanoseconds.

#get_time_seconds () or #get_time_s ():
  Returns wall clock time on the local machine in seconds.

#sleep (double time_to_sleep in s):
  Sleeps for at least the specified time and returns time
  spent sleeping in seconds.

The madara::knowledge::KnowledgeBase keeps a Lamport clock for itself and also keeps individual Lamport clocks for each variable within the KnowledgeBase. These clocks are used to ensure consistency of knowledge during updates from external agents. To access these Lamport clocks, users should use the KaRL system calls noted above.

Thread Timing Control

The main manager of threads and time related to thread execution is the madara::threads::Threader class. To get predictable executions of threads that subclass from madara::threads::BaseThread, you use the Threader::run with a provided hertz rate (specified as a double).

madara::threads::Threader threader;

// run threads at 10hz and 1hz
threader.run (10.0, "analyzer", new AnalyzerThread ());
threader.run (1.0, "enforcer", new EnforcerThread ());

// sleep for 60 seconds (this sleep is a hard sleep that ignores interrupts)
madara::utility::sleep (60.0)

The Threader enforces epochs to limit bursty behavior and control the execution of tasks. If a task runs over its epoch, it is not necessarily immediately run but instead run at the appropriate epoch as shown in the figure above.

Wiki: Home