doc/design.xml

   1 <?xml version='1.0'?>
   2 <doc  style="main.css">
   3 <book>
   4 <chapter>
   5 <heading>Introduction</heading>
   6
   7 <para>
   8 To test software that depends on time, using the actual time is usually not feasable or even possible. To perform actons during a certain time period, a test can be speeded up if an accelerated time is used. Another example is software that acts on a specific date. To test such software the environment in which the program runs needs to set the date to that value instead of using the actual date.
   9 To facilitate testing of time dependent software, a virtual timebase is needed. This timebase will provide the virtual time to the system under test while the virtual time can be controlled by the test framework. When the time dependent software is not being tested but runs in actual operation the virtual time must be equal to the actual time.
  10 </para>
  11 <para>
  12 Tachyon provides a virtual timebase with an interface that replaces system calls such as nanosleep(2) and time(2). Instead of using these system calls, a program would call Tachyon::nanosleep() and Tachyon::time().
  13 </para>
  14 <para>
  15 Features of the Tachyon class include:
  16
  17 <itemize>
  18 <item>
  19 Wait for a specified time interval, multiple parallel timers in separate threads.
  20 </item>
  21 <item>
  22 Provide the current virtual time.
  23 </item>
  24 <item>
  25 Send notifications after a timer interval, periodically and at a point in time.
  26 </item>
  27 </itemize>
  28 </para>
  29 <para>
  30 Functions to control the virtual timebase:
  31 <itemize>
  32 <item>
  33 Accelerate time by a factor.
  34 </item>
  35 <item>
  36 Set a specific time. Controllable from external process.
  37 </item>
  38 </itemize>
  39 </para>
  40 <para>
  41 Example of performing an action every minute for 10 minutes:
  42 </para>
  43
  44 <example>
  45 Tachyon timebase;
  46 struct timespec interval;
  47
  48 interval.tv_sec = 60;
  49 interval.tv_nsec = 0;
  50
  51 std::cout &lt;&lt; "Tachyon name is " &lt;&lt; timebase.name() &lt;&lt; "\n";
  52 for (int i = 0; i &lt; 10; i++)
  53 {
  54    timebase.nanosleep(interval);
  55    std::cout &lt;&lt; "One minute.\n"
  56 }
  57
  58 </example>
  59
  60 <para>
  61 Testing this in actual time would at least take 10 minutes. To speed up the test, the Tachyon object is instructed by a test program to accellerate time:
  62 </para>
  63
  64 <example>
  65
  66 std::cin &gt;&gt; tachyon_name;
  67
  68 Tachyon testtime(tachyon_name);
  69
  70 testtime.accellerate(30);
  71
  72 while (std::cin &gt;&gt; report)
  73 {
  74    std::cout &lt;&lt; report;
  75 }
  76
  77 </example>
  78
  79
  80
  81 <para>
  82 The virtual time is calculated by using an offset o and an acceleration factor a in a simple linear function:
  83 </para>
  84
  85 <pre>
  86     Tv = T0 + a * (Ta - T0) + o
  87 </pre>
  88
  89 <para>
  90 T0 is the time at the moment of changing the accelleration.
  91
  92 By default, the acceleration is 1.0 and the offset is 0, rendering the virtual time equal to the actual time.
  93 </para>
  94
  95 <para>
  96 To control the virtual time from an external process, a form of inter process communication (IPC) is used. The external process, usually a test program, can find the Tachyon object to control through a name which is assigned for that Tachyon object. Two or more Tachyon objects may exist, one of which holds the virtual time used by the time dependent software. The other Tachyon object(s) are used to control the virtual timebase and send the timebase parameters through a form of IPC.
  97 </para>
  98
  99 </chapter>
 100
 101 <chapter>
 102 <heading>The Tachyon class</heading>
 103
 104 <section>
 105 <heading>Methods</heading>
 106
 107 <description>
 108 <item tag='Tachyon()'>
 109 The default contructor creates a Tachyon object that can receive changes to its parameters. It opens an IPC resource (e.g. a message queue) and will make the name of that resource available with the name() method.
 110 </item>
 111
 112 <item tag='Tachyon(const char *name)'>
 113 Creates a Tachyon object that will send the parameters to another Tachyon object which is referred to by name. Note that name is not the name of this object but of the object which is controlled by this object.
 114 </item>
 115
 116 <item tag='~Tachyon()'>
 117 The destructor closes any open IPC resources.
 118 </item>
 119
 120 <item tag='const char * name(void)'>
 121 Return the name of the IPC resource that can be used to control this object.
 122 </item>
 123
 124 <item tag='time_t time(void)'>
 125 Return the virtual in second since the Epoch. See also time(2).
 126 </item>
 127
 128 <item tag='int nanosleep(struct timespec req)'>
 129 Suspend execution until the time in req is passed. That time is divided by the accelleration set in the Tachyon object. So, if a waiting time of 60 seconds is requested and the accelleration is 10, execution will be actually be suspended for 6 seconds.
 130 </item>
 131
 132 <item tag='settime (time_t sec)'>
 133 Set the time to sec seconds since the Epoch. The vitual time will continue from that point onwards.
 134 </item>
 135
 136 <item tag='accellerate(double factor)'>
 137 Set the accelleration factor of the virtual time. A factor &gt; 1.0 will speed things up and will make the actual sleep tine shorter then the time requested. A factor &lt; 1.0 will slow the virtual time down.
 138 </item>
 139 </description>
 140
 141 </section>
 142
 143 <section>
 144 <heading>Protocol</heading>
 145
 146 <para>
 147 The parameters to control a Tachyon object are the accelleration factor and the time offset.
 148 These parameters are controlled by sending messages to the Tachyon object's message queue in ASCII format.
 149 A message starts with a single letter to select the parameter, followed by a number for the parameter's value.
 150 The letter can be 'A' for the accelleration or 'T' for the time.
 151 To set the accelleration the message is 'A', immediately followed by a number. This number can be a floating point number.
 152 For example, the message:
 153 <verbatim>
 154    A2.5
 155 </verbatim>
 156 makes the virtaul time run 2.5 times faster.
 157 The virtual clock is set to a specific time by sending a 'T' followed by an integer number.
 158 The number is the number of seconds since the epoch (1970-01-01 00:00:00 +0000 (UTC)).
 159 For example:
 160 <verbatim>
 161    T1563942575
 162 </verbatim>
 163 sets the time to Jul 24 06:29:35 CEST 2019.
 164 </para>
 165
 166 </section>
 167
 168 <section>
 169 <heading>tachyon control command</heading>
 170
 171 <verbatim>
 172 tachyon [options] tachyon-name.
 173
 174 Allowed options:
 175   -h [ --help ]              produce help message
 176   --tachyon-name arg         tachyon name
 177   -a [ --accelleration ] arg set time acceleration factor
 178   -t [ --time ] arg          set time value in seconds
 179
 180 </verbatim>
 181
 182
 183 </section>
 184
 185 </chapter>
 186 </book>
 187 </doc>