Recent changes to Time

Time modified by James Edmondson

James Edmondson — Sat, 24 Mar 2018 05:28:34 -0000

--- v6
+++ v7
@@ -68,6 +68,6 @@

 ~~~~~~

-
+

 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.

Time modified by James Edmondson

James Edmondson — Fri, 23 Mar 2018 22:01:53 -0000

--- v5
+++ v6
@@ -26,6 +26,7 @@
 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)](http://madara.sourceforge.net/docs/cpp/de/d04/namespacemadara_1_1utility.html#a4e39cc1be95c5d37764e81b2f7f386b3): 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)](http://madara.sourceforge.net/docs/cpp/de/d04/namespacemadara_1_1utility.html#ad4e12fb49ead09091eed559c5318e2a9): 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)](http://madara.sourceforge.net/docs/cpp/de/d04/namespacemadara_1_1utility.html#ab842b817b5f645f774b389bed04c8c11): returns time of day in nanoseconds (useful for duration timestamps).

Time modified by James Edmondson

James Edmondson — Fri, 23 Mar 2018 21:59:35 -0000

--- v4
+++ v5
@@ -2,7 +2,7 @@

 ----

-**Time Utilities**
+# 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.

@@ -23,11 +23,12 @@
 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:*
-* [madara::utility::sleep (double seconds)](http://madara.sourceforge.net/docs/cpp/de/d04/namespacemadara_1_1utility.html#a4e39cc1be95c5d37764e81b2f7f386b3): hard sleep that ignores OS interrupts and guarantees a sleep as long as the time specified in wall clock time. 
-* [madara::utility::sleep (ACE_Time_Value)](http://madara.sourceforge.net/docs/cpp/de/d04/namespacemadara_1_1utility.html#ad4e12fb49ead09091eed559c5318e2a9): 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.)
-* [madara::utility::get_time (void)](http://madara.sourceforge.net/docs/cpp/de/d04/namespacemadara_1_1utility.html#ab842b817b5f645f774b389bed04c8c11): returns time of day in nanoseconds (useful for duration timestamps). 
+* Sleep: [madara::utility::sleep (double seconds)](http://madara.sourceforge.net/docs/cpp/de/d04/namespacemadara_1_1utility.html#a4e39cc1be95c5d37764e81b2f7f386b3): 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)](http://madara.sourceforge.net/docs/cpp/de/d04/namespacemadara_1_1utility.html#ad4e12fb49ead09091eed559c5318e2a9): 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)](http://madara.sourceforge.net/docs/cpp/de/d04/namespacemadara_1_1utility.html#ab842b817b5f645f774b389bed04c8c11): 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](https://sourceforge.net/p/madara/code/ci/master/tree/docs/system_calls.txt)
 ~~~~~~
@@ -46,9 +47,11 @@
   spent sleeping in seconds.
 ~~~~~~

+The [madara::knowledge::KnowledgeBase](http://madara.sourceforge.net/docs/cpp/da/d1c/classmadara_1_1knowledge_1_1KnowledgeBase.html)  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.
+
 ----

-**Threads**
+# Thread Timing Control

 The main manager of threads and time related to thread execution is the [madara::threads::Threader](http://madara.sourceforge.net/docs/cpp/d8/de5/classmadara_1_1threads_1_1Threader.html) class. To get predictable executions of threads that subclass from [madara::threads::BaseThread](http://madara.sourceforge.net/docs/cpp/de/dcd/classmadara_1_1threads_1_1BaseThread.html), you use the `Threader::run` with a provided hertz rate (specified as a double).

Time modified by James Edmondson

James Edmondson — Fri, 23 Mar 2018 21:53:33 -0000

--- v3
+++ v4
@@ -6,13 +6,45 @@

 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);
+~~~~~~
+
+
 *MADARA also provides standard get time and sleep related functions, including:*
 * [madara::utility::sleep (double seconds)](http://madara.sourceforge.net/docs/cpp/de/d04/namespacemadara_1_1utility.html#a4e39cc1be95c5d37764e81b2f7f386b3): hard sleep that ignores OS interrupts and guarantees a sleep as long as the time specified in wall clock time. 
-* [madara::utility::sleep (ACE_Time_Value)(http://madara.sourceforge.net/docs/cpp/de/d04/namespacemadara_1_1utility.html#ad4e12fb49ead09091eed559c5318e2a9): 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.)
+* [madara::utility::sleep (ACE_Time_Value)](http://madara.sourceforge.net/docs/cpp/de/d04/namespacemadara_1_1utility.html#ad4e12fb49ead09091eed559c5318e2a9): 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.)
 * [madara::utility::get_time (void)](http://madara.sourceforge.net/docs/cpp/de/d04/namespacemadara_1_1utility.html#ab842b817b5f645f774b389bed04c8c11): returns time of day in nanoseconds (useful for duration timestamps). 

-*MADARA has time functions inside of the KaRL scripting language:*
-* 
+*MADARA has time system calls inside of the KaRL scripting language:* [Full List of System Calls](https://sourceforge.net/p/madara/code/ci/master/tree/docs/system_calls.txt)
+~~~~~~
+#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.
+~~~~~~

 ----

Time modified by James Edmondson

James Edmondson — Fri, 23 Mar 2018 21:45:48 -0000

--- v2
+++ v3
@@ -6,7 +6,13 @@

 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.

-MADARA also provides standard get time functions
+*MADARA also provides standard get time and sleep related functions, including:*
+* [madara::utility::sleep (double seconds)](http://madara.sourceforge.net/docs/cpp/de/d04/namespacemadara_1_1utility.html#a4e39cc1be95c5d37764e81b2f7f386b3): hard sleep that ignores OS interrupts and guarantees a sleep as long as the time specified in wall clock time. 
+* [madara::utility::sleep (ACE_Time_Value)(http://madara.sourceforge.net/docs/cpp/de/d04/namespacemadara_1_1utility.html#ad4e12fb49ead09091eed559c5318e2a9): 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.)
+* [madara::utility::get_time (void)](http://madara.sourceforge.net/docs/cpp/de/d04/namespacemadara_1_1utility.html#ab842b817b5f645f774b389bed04c8c11): returns time of day in nanoseconds (useful for duration timestamps). 
+
+*MADARA has time functions inside of the KaRL scripting language:*
+* 

 ----

Time modified by James Edmondson

James Edmondson — Fri, 23 Mar 2018 21:39:12 -0000

--- v1
+++ v2
@@ -17,7 +17,7 @@
 ~~~~~~
 madara::threads::Threader threader;

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

Time modified by James Edmondson

James Edmondson — Fri, 23 Mar 2018 21:38:40 -0000

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.

MADARA also provides standard get time functions

Threads

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 50hz 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.