[doc] realtime() page improved
[scilab.git] / scilab / modules / time / help / en_US / realtime.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA -
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2018 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19           xml:lang="en" xml:id="realtime">
20     <refnamediv xml:id="realtimeinit">
21         <refname>realtimeinit</refname>
22         <refpurpose>sets the time unit</refpurpose>
23     </refnamediv>
24     <refnamediv>
25         <refname>realtime</refname>
26         <refpurpose>sets the initial datetime and starts the chronometer, or waits until a given datetime</refpurpose>
27     </refnamediv>
28     <refsynopsisdiv>
29         <title>Syntax</title>
30         <synopsis>
31             realtimeinit(time_unit)
32             realtime(t0)
33             realtime(t)
34         </synopsis>
35     </refsynopsisdiv>
36     <refsection>
37         <title>Arguments</title>
38         <variablelist>
39             <varlistentry>
40                 <term>time_unit</term>
41                 <listitem>
42                     <para>
43                         positive decimal number: time unit duration, in seconds.
44                     </para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>t0</term>
49                 <listitem>
50                     <para>
51                        decimal number: initial datetime, in <literal>time_unit</literal>.
52                        This meaning holds when <literal>realtime(…)</literal> is called for the
53                        first time after the last <literal>realtimeinit(…)</literal>.
54                        This first call sets the datetime origin and restarts the real timer.
55                     </para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>t</term>
60                 <listitem>
61                     <para>decimal number: datetime up to which Scilab must wait before performing
62                     the next instruction, expressed in time unit.
63                     </para>
64                 </listitem>
65             </varlistentry>
66         </variablelist>
67     </refsection>
68     <refsection>
69         <title>Description</title>
70         <para>
71             While <literal>sleep(d)</literal> waits for a given fixed duration,
72             <literal>realtime(t)</literal> will wait the required (unknown) time to reach the
73             given datetime <varname>t</varname>.
74         </para>
75         <para>
76             <literal>realtimeinit(time_unit)</literal>  defines the time unit in which the
77             datetime <varname>t</varname> specified by <literal>realtime</literal> is expressed.
78         </para>
79         <para>
80             After calling <literal>realtimeinit(time_unit)</literal>, the first call to
81             <literal>realtime(t0)</literal> sets the current datetime to <literal>t0</literal>,
82             without any wait. Each new call to <literal>realtime(t)</literal> then waits till
83             datetime <varname>t</varname> is reached. If <varname>t</varname> is already passed,
84             no wait is added.
85         </para>
86     </refsection>
87     <refsection>
88         <title>Examples</title>
89         <para>
90         In the following example, in a loop, a job takes an arbitrary time, from
91         0 to 1.50 s. This is simulated with a sleep() of random duration. Although this period
92         is not regular, realtime() is used to compensate and print something every 2.00 seconds:
93         </para>
94         <programlisting role="example"><![CDATA[
95 clc
96 tic();
97 realtimeinit(2.00);
98 realtime(0);
99 for k = 1:10
100     if k==1, mprintf("\nSleep for  Wake-up at   Wait until date\n"), end
101     d = rand(1,1);
102     sleep(d*1500);
103     mprintf(' %4.2f s     %5.2f s', d*1.5, toc());
104     realtime(k);
105     mprintf('      %5.2f s\n', toc());
106 end
107  ]]></programlisting>
108     <screen><![CDATA[
109 Sleep for  Wake-up at   Wait until date
110  0.28 s      0.57 s       2.08 s
111  0.03 s      2.11 s       4.08 s
112  1.27 s      5.34 s       6.08 s
113  0.11 s      6.19 s       8.08 s
114  1.28 s      9.36 s      10.08 s
115  0.02 s     10.10 s      12.08 s
116  0.28 s     12.36 s      14.08 s
117  0.74 s     14.82 s      16.08 s
118  1.12 s     17.20 s      18.08 s
119  1.41 s     19.49 s      20.08 s
120 ]]></screen>
121     </refsection>
122     <refsection role="see also">
123         <title>See also</title>
124         <simplelist type="inline">
125             <member>
126                 <link linkend="sleep">sleep</link>
127             </member>
128             <member>
129                 <link linkend="getdate">getdate</link>
130             </member>
131             <member>
132                 <link linkend="waitbar">waitbar</link>
133             </member>
134             <member>
135                 <link linkend="progressionbar">progressionbar</link>
136             </member>
137         </simplelist>
138     </refsection>
139 </refentry>