ACE/docs/ACE-monotonic-timer.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2 <!--  -->
   3 <HTML>
   4 <HEAD>
   5         <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
   6         <TITLE></TITLE>
   7         <META NAME="GENERATOR" CONTENT="LibreOffice 3.5  (Linux)">
   8         <META NAME="AUTHOR" CONTENT="Martin Corino">
   9         <META NAME="CREATED" CONTENT="20120802;12245200">
  10         <META NAME="CHANGEDBY" CONTENT="Martin Corino">
  11         <META NAME="CHANGED" CONTENT="20120816;12280900">
  12         <STYLE TYPE="text/css">
  13         <!--
  14                 @page { margin: 0.79in }
  15                 P { margin-bottom: 0.08in }
  16                 H1 { margin-bottom: 0.08in }
  17                 H1.western { font-family: "Liberation Sans", sans-serif; font-size: 16pt }
  18                 H1.cjk { font-family: "Droid Sans Fallback"; font-size: 16pt }
  19                 H1.ctl { font-family: "Arial"; font-size: 16pt }
  20                 H2 { margin-bottom: 0.08in }
  21                 H2.western { font-family: "Liberation Sans", sans-serif; font-size: 14pt; font-style: italic }
  22                 H2.cjk { font-family: "Droid Sans Fallback"; font-size: 14pt; font-style: italic }
  23                 H2.ctl { font-size: 14pt; font-style: italic }
  24                 H3 { margin-bottom: 0.08in }
  25                 H3.western { font-family: "Liberation Sans", sans-serif; font-size: 13pt }
  26                 H3.cjk { font-family: "Droid Sans Fallback" }
  27                 PRE { margin-left: 0.20in; margin-bottom: 0.20in; border-top: none; border-bottom: none; border-left: 1.05pt solid #808080; border-right: none; padding-top: 0in; padding-bottom: 0in; padding-left: 0.02in; padding-right: 0in }
  28                 PRE.cjk { font-family: "Droid Sans Fallback", monospace }
  29         -->
  30         </STYLE>
  31 </HEAD>
  32 <BODY LANG="en-US" DIR="LTR">
  33 <DIV TYPE=HEADER>
  34         <P STYLE="margin-bottom: 0in">Author: M.J.N. Corino             Copyright <FONT FACE="Liberation Serif, serif">©</FONT><FONT FACE="Liberation Serif, serif">
  35         2012, Remedy IT</FONT></P>
  36         <P STYLE="margin-bottom: 0.2in"><FONT FACE="Liberation Serif, serif">Date:
  37         November 06, 2012               The Netherlands</FONT></P>
  38 </DIV>
  39 <H1 CLASS="western">Monotonic timer support for ACE conditions and events</H1>
  40 <H2 CLASS="western">Introduction</H2>
  41 <P>This document describes how to use the changes to the ACE API
  42 which provide support to use monotonic timers for condition and event
  43 variables to solve the problem of system timeshift vulnerability of
  44 the ACE Condition and Event variable timeout functionality.</P>
  45 <H2 CLASS="western">Background</H2>
  46 <P>ACE Condition and Event variables implement an API to wait for the
  47 condition or event to be signalled with a maximum wait timeout value.
  48 This timeout value must be specified as <B>absolute time</B><SPAN STYLE="font-weight: normal">
  49 (this API spec has been derived from the POSIX threading API,
  50 pthread, the most widely available, standardized, threading API
  51 available) or, in the case of events, optionally as relative time
  52 (converted to absolute time by ACE on certain platforms).</SPAN></P>
  53 <P><SPAN STYLE="font-weight: normal">Currently ACE expects the
  54 timeout value to be based on the system time clock through the ACE
  55 API support for that clock (</SPAN><I><SPAN STYLE="font-weight: normal">ACE_OS::gettimeofday
  56 ()</SPAN></I><SPAN STYLE="font-weight: normal">) which is also the
  57 default for the POSIX API (originally POSIX did not support anything
  58 else).</SPAN></P>
  59 <P STYLE="font-weight: normal">This dependency on the system time
  60 clock however makes ACE Condition and Event variables vulnerable to
  61 system clock time shifts since a change in the system clock time setting
  62 after an absolute time value has been determined (based on the
  63 unchanged system clock) will influence the outstanding wait
  64 operations based on these time values.</P>
  65 <P STYLE="font-weight: normal">The ACE implementation for the Windows
  66 platform does not use the POSIX interface but is still potentially
  67 vulnerable because the ACE implementation itself performs a
  68 conversion from absolute to relative time before executing wait
  69 operation on a Condition variable (as this is what the Win32 API
  70 expects). Since this conversion is based on the system time clock
  71 here also a vulnerability exists.</P>
  72 <P STYLE="font-weight: normal">To resolve this vulnerability the
  73 notion of MONOTONIC timer sources should be integrated into the ACE
  74 Condition and Event support. MONOTONIC timers are timer sources which are
  75 independent of the system time clock and will always return time
  76 values which are correct relative to previously returned time values
  77 (at least within the lifetime of a single running process).</P>
  78 <P STYLE="font-weight: normal">The customer encountered this problem
  79 while making use of the ACE_Message_Queue classes in the
  80 implementation of their application. The enqueue/dequeue functionality
  81 of the message queues makes heavy use of the ACE Condition variable
  82 timed wait support. The customer also used ACE_Event derived classes
  83 which suffer from the same vulnerability.</P>
  84 <H2 CLASS="western">Requirements</H2>
  85 <P STYLE="font-weight: normal">Prerequisites for the solution are:</P>
  86 <UL>
  87         <LI><P STYLE="font-weight: normal">maintain backward compatibility
  88         (as for all changes made to the ACE API) and cross platform
  89         stability (if not full support on all platforms);</P>
  90         <LI><P STYLE="font-weight: normal">create an implementation that
  91         allows for integration in the customers application with minimal
  92         code changes;</P>
  93         <LI><P STYLE="font-weight: normal">create an implementation allowing
  94         for staged completion in the full ACE API, i.e. only change those
  95         parts of ACE now that are essential to the solution of the customer
  96         problem and postpone any non-essential changes without losing
  97         library consistency and stability.</P>
  98 </UL>
  99 <H2 CLASS="western"><B>Solution</B></H2>
 100 <P STYLE="font-weight: normal">The implemented solution involves
 101 adding support for the ACE Time_Policy traits in the ACE Condition
 102 and Event APIs and those classes directly related to the ACE Condition
 103 and Event timed wait functionality that are used by the customer (like
 104 ACE_Event, ACE_Message_Queue and ACE_Task). Also some classes tightly linked to
 105 those classes have been updated.</P>
 106 <P STYLE="font-weight: normal">The newly added monotonic time policy,
 107 ACE_Monotonic_Time_Policy, provides support for monotonic time values
 108 (on Windows and any POSIX platform providing the necessary support
 109 like recent versions of Linux).</P>
 110 <P STYLE="font-weight: normal">New (virtual) functionality in
 111 ACE_Time_Value combined with a derived template class
 112 (ACE_Time_Value_T&lt;&gt;) provide time policy awareness in time
 113 values.</P>
 114 <P STYLE="font-weight: normal">Using the combination of these changes
 115 it is now possible to set up message queues that support monotonic
 116 time values for timed wait methods in a portable way as will be shown
 117 in the following section.</P>
 118 <H2 CLASS="western" STYLE="page-break-before: always">User Code Changes</H2>
 119 <P STYLE="font-weight: normal">The following are examples of user
 120 code changes required to update an application to support monotonic
 121 timed message queues.</P>
 122 <P STYLE="font-weight: normal">Message_Queue and Task class templates
 123 have been provided with an additional template argument to specify
 124 the Time_Policy to use for condition variables. To use monotonic time
 125 values the new ACE_Monotonic_Time_Policy should be used.
 126 </P>
 127 <P STYLE="font-weight: normal">So, where an existing application
 128 declared a Message_Queue as:</P>
 129 <PRE CLASS="western" STYLE="font-weight: normal">ACE_Message_Queue&lt;ACE_MT_SYNCH&gt; msg_queue_;</PRE><P STYLE="font-weight: normal">
 130 </P>
 131 <P STYLE="font-weight: normal">this would need to change to:</P>
 132 <PRE CLASS="western" STYLE="font-weight: normal">ACE_Message_Queue&lt;ACE_MT_SYNCH, ACE_Monotonic_Time_Policy&gt; msg_queue_;</PRE><P STYLE="font-weight: normal">
 133 </P>
 134 <P STYLE="font-weight: normal">The changes for task are similar:</P>
 135 <PRE CLASS="western" STYLE="font-weight: normal">class MyTask : public ACE_Task&lt;ACE_MT_SYNCH&gt;
 136 {
 137   …
 138 };</PRE><P STYLE="font-weight: normal">
 139 should change to:</P>
 140 <PRE CLASS="western" STYLE="font-weight: normal">class MyTask : public ACE_Task&lt;ACE_MT_SYNCH, ACE_Monotonic_Time_Policy&gt;
 141 {
 142   …
 143 };</PRE><P STYLE="font-weight: normal">
 144 </P>
 145 <P STYLE="font-weight: normal">To specify timeout values to these
 146 message queues on the enqueue/dequeue operations you would have to
 147 use time values that are Time_Policy aware. To that end a templated
 148 derivative of ACE_Time_Value has been implemented allowing one to
 149 declare a time value as:</P>
 150 <PRE CLASS="western" STYLE="font-weight: normal">ACE_Time_Value_T&lt;ACE_Monotonic_Time_Policy&gt; timeout_;</PRE><P STYLE="font-weight: normal">
 151 </P>
 152 <P STYLE="font-weight: normal">The updated Message_Queue and Task
 153 classes provide a convenience method to initialize such a  time value
 154 with the time policy based time of day as follows:</P>
 155 <PRE CLASS="western" STYLE="font-weight: normal">ACE_Time_Value_T&lt;ACE_Monotonic_Time_Policy&gt;
 156         timeout_ (msg_queue_.gettimeofday ());
 157 <B>// or</B>
 158 ACE_Time_Value_T&lt;ACE_Monotonic_Time_Policy&gt; timeout_;
 159 timeout_ = msg_queue_.gettimeofday ();</PRE><P STYLE="font-weight: normal">
 160 </P>
 161 <P STYLE="font-weight: normal">The return type of this method is a
 162 time policy specific time value as follows:</P>
 163 <PRE CLASS="western" STYLE="font-weight: normal">template &lt;ACE_SYNCH_DECL, class TIME_POLICY&gt;
 164 class ACE_Message_Queue : public ACE_Message_Queue_Base
 165 {
 166 …
 167 ACE_Time_Value_T&lt;TIME_POLICY&gt; gettimeofday () const;
 168 …
 169 };</PRE><P STYLE="font-weight: normal">
 170 </P>
 171 <P STYLE="font-weight: normal">To define a wait timeout of 5 sec and
 172 execute an enqueue operation the following would apply:</P>
 173 <PRE CLASS="western" STYLE="font-weight: normal">...
 174 ACE_Time_Value_T&lt;ACE_Monotonic_Time_Policy&gt; timeout_;
 175 timeout_ = msg_queue_.gettimeofday ();
 176 timeout_ += ACE_Time_Value (5,0);
 177 msg_queue_.enqueue (msg_block, &amp;timeout_);
 178 …</PRE><P STYLE="font-weight: normal">
 179 </P>
 180 <P STYLE="font-weight: normal">Similar changes apply to the refactored ACE_Event classes. In
 181 addition to the added support for time policies also a new base class is introduced to allow
 182 for generic use of an Event variable after instantiation of a specific time policy based type.</P>
 183 <PRE CLASS="western" STYLE="font-weight: normal">
 184 …
 185 // declare an Event variable
 186 ACE_Event_Base &amp;evt;
 187 …
 188 // initialize Event variable
 189 ACE_Manual_Event_T&lt;ACE_Monotonic_Time_Policy&gt; mono_evt;
 190 evt = mono_evt;
 191 …
 192 // wait 5 sec for event to be signalled
 193 ACE_Time_Value_T&lt;ACE_Monotonic_Time_Policy&gt; timeout_;
 194 timeout_ = timeout_.now ();
 195 timeout_ += ACE_Time_Value (5,0);
 196 evt.wait (&amp;timeout_);
 197 …
 198 // OR (using relative timeout)
 199 …
 200 ACE_Time_Value_T&lt;ACE_Monotonic_Time_Policy&gt; timeout_ (5,0);
 201 evt.wait (&amp;timeout_, 0);
 202 </PRE><P STYLE="font-weight: normal">
 203 </P>
 204 <P><B>NOTE:</B><SPAN STYLE="font-weight: normal"> To function
 205 properly the ACE_Time_Value pointer passed to the timed wait methods
 206 </SPAN><B>MUST</B><SPAN STYLE="font-weight: normal"> be the address
 207 of an ACE_Time_Value_T&lt;TIME_POLICY&gt; instance which matches the
 208 TIME_POLICY of the message queue or task. This is because the lower
 209 layers now rely on the new time policy aware virtual methods of the
 210 ACE_Time_Value classes to perform time calculations (to_relative_time
 211 (), to_absolute_time (), now ()).<BR>Unfortunately due to backward
 212 compatibility issues it was not possible to change the signatures of
 213 the timed wait methods to type safe versions accepting only correct
 214 time value instances.</SPAN></P>
 215 <P><B>NOTE2:</B><SPAN STYLE="font-weight: normal"> Please be aware of
 216 the differences in behaviour of the time calculation operations.</SPAN></P>
 217 <UL>
 218         <LI><P><I><SPAN STYLE="font-weight: normal">unary</SPAN></I><SPAN STYLE="font-style: normal"><SPAN STYLE="font-weight: normal">
 219         calculations (-=, += ,*=, –, ++) maintain time policy awareness,
 220         i.e. these operations always return a time policy aware time value
 221         (ACE_Time_Value_T&lt;&gt; instance; which may a reference to the
 222         time value itself);</SPAN></SPAN></P>
 223         <LI><P><I><SPAN STYLE="font-weight: normal">binary</SPAN></I><SPAN STYLE="font-style: normal"><SPAN STYLE="font-weight: normal">
 224         calculations (+, -, *) always return a default ACE_Time_Value
 225         instance and thus loose time policy awareness. The basic numeric
 226         time values contained in these instances should only be used for
 227         comparative purposes or to update the value of a time policy based
 228         instance like:</SPAN></SPAN></P>
 229 </UL>
 230 <PRE CLASS="western" STYLE="font-style: normal; font-weight: normal">ACE_Time_Value_T&lt;ACE_Monotonic_Time_Policy&gt; t1, t2;
 231 … // t1 and t2 get assigned values
 232 // calculate difference between t1 and t2
 233 ACE_Time_Value tdiff = t2 – t1;
 234 …
 235 // at some point calculate new absolute time based on tdiff
 236 ACE_Time_Value_T&lt;ACE_Monotonic_Time_Policy&gt; tv;
 237 // now () returns an ACE_Time_Value representing current time according
 238 // to the active time policy of tv
 239 tv = tv.now () + tdiff;</PRE><P STYLE="font-style: normal; font-weight: normal">
 240 </P>
 241 <P STYLE="font-style: normal; font-weight: normal">More examples code
 242 can be found in the following regression tests</P>
 243 <UL>
 244         <LI><P STYLE="font-style: normal; font-weight: normal">$ACE_ROOT/tests/Bug_4055_Regression</P>
 245         <LI><P STYLE="font-style: normal; font-weight: normal">$ACE_ROOT/tests/Monotonic_Task_Test</P>
 246         <LI><P STYLE="font-style: normal; font-weight: normal">$ACE_ROOT/tests/Monotonic_Message_Queue_Test</P>
 247   <LI><P STYLE="font-style: normal; font-weight: normal">$ACE_ROOT/tests/Monotonic_Manual_Event_Test</P>
 248 </UL>
 249
 250 <h2 class="western">Testing for Monotonic Time Support</h2>
 251
 252 <p>Support for monotonic time in ACE can be determined by testing for the
 253 existence of these two preprocessor macros that would be defined by ACE
 254 platform headers:</p>
 255
 256 <ul>
 257 <li><p>
 258   The <code>ACE_HAS_MONOTONIC_TIME_POLICY</code> preprocessor macro is defined
 259   when <code>ACE_Monotonic_Time_Policy</code> by itself should be supported.
 260 </p></li>
 261 <li><p>
 262   The <code>ACE_HAS_MONOTONIC_CONDITIONS</code> preprocessor macro is defined
 263   when <code>ACE_Condition</code>s should support waiting for a monotonic point
 264   in time using
 265   <code>ACE_Condition_Attributes&lt;ACE_Monotonic_Time_Policy&gt;</code>.
 266 </p></li>
 267 </ul>
 268
 269 <DIV TYPE=FOOTER>
 270         <P STYLE="margin-top: 0.2in; margin-bottom: 0in"><BR>
 271         </P>
 272 </DIV>
 273 </BODY>
 274 </HTML>