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>