* Bug 14425 fixed - xpause() set obsolete, merged in sleep(). sleep(,'s') implemented
[scilab.git] / scilab / modules / time / help / en_US / sleep.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) 2016 - Samuel GOUGEON
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
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" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="sleep">
17     <refnamediv>
18         <refname>sleep</refname>
19         <refpurpose>suspend all code executions (console, scripts, callbacks,..)</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>
24             sleep(milliseconds)
25             sleep(seconds, "s")
26         </synopsis>
27     </refsynopsisdiv>
28     <refsection role="arguments">
29         <title>Arguments</title>
30         <variablelist>
31             <varlistentry>
32                 <term>milliseconds</term>
33                 <listitem>duration of the sleep, in milliseconds (decimal number)
34                 </listitem>
35             </varlistentry>
36             <varlistentry>
37                 <term>seconds</term>
38                 <listitem>duration of the sleep, in seconds (decimal number)
39                 </listitem>
40             </varlistentry>
41         </variablelist>
42     </refsection>
43     <refsection>
44         <title>Description</title>
45         <para>
46             <function>sleep</function> stops Scilab processing any instruction for
47             a specified number of miliseconds or seconds:
48             <para>
49                 <variablelist>
50                     <varlistentry>
51                         <term>Console:</term>
52                         <listitem> input and output in console are suspended.
53                             <warning>The CTRL-C interruption is caught but performed only at
54                                 the end of the sleep.
55                             </warning>
56                         </listitem>
57                     </varlistentry>
58                     <varlistentry>
59                         <term>Scripts and functions:</term>
60                         <listitem>
61                             When <function>sleep(..)</function>
62                             is called inside a script or a function, Scilab waits for the
63                             given duration before processing the next instruction.
64                             CTRL-C in the console is caught but performed only at the end of
65                             the sleep.
66                         </listitem>
67                     </varlistentry>
68                     <varlistentry>
69                         <term>callbacks:</term>
70                         <listitem> .. are actions triggered by interactions
71                             with menus and with <literal>uicontrol</literal> interactive
72                             graphical components. During the sleep(..), these interactions
73                             are caught, and related instructions are buffered.
74                             Buffered actions are all performed after sleep()'s end.
75                         </listitem>
76                     </varlistentry>
77                     <varlistentry>
78                         <term>Graphics interactions:</term>
79                         <listitem>
80                             <function>sleep(..)</function>
81                             does not prevent interacting with graphics, providing that the
82                             interaction mode has been turned on before entering the sleep.
83                             Then, moving curves, editing graphics labels, etc is still
84                             possible during Scilab's sleep. The wake-up does not reset these
85                             actions.
86                         </listitem>
87                     </varlistentry>
88                 </variablelist>
89             </para>
90             <note>Time resolution:
91                 <simplelist>
92                     <member>Windows systems: 0.5 ms</member>
93                     <member>Linux systems: 1 ┬Ás</member>
94                 </simplelist>
95             </note>
96             <warning>Time resolution is not.. time accuracy: The actual suspension
97                 time may be longer than the specified one, due to other processes run
98                 in the system, or due to the time spent to process the call.
99             </warning>
100         </para>
101     </refsection>
102     <refsection>
103         <title>Examples</title>
104         <programlisting role="example"><![CDATA[
105 // Simple examples
106 tic; sleep(4350); toc
107 tic; sleep(4.35, "s"); toc
108
109 // Testing the sleep's accuracy:
110 results = [];
111 disp("Please wait... sleep()s and wake-up are performed...")
112 for i = -1:4
113     dt = 10^i;        // specified duration [ms]
114     tic;
115     sleep(dt);
116     dta = toc()*1000; // actual duration [ms]
117     results = [results ; dt dta ];
118 end
119 results
120
121 // Test of the CTRL-C interruption:
122 disp("Press CTRL + C keys now: the 15 s sleep is going on")
123 sleep(15,"s")
124
125 // Test of interactions with menus:
126 clf
127 plot2d()
128 // [If you are a MacOS user, select the menu "Edit=> Clear figure" instead]
129 mprintf("During this 30s sleep, click on the figure\n  then on its menu ""Edit => Figure properties""")
130 // The graphical editor will be actually called only at wake-up
131  ]]></programlisting>
132     </refsection>
133     <refsection role="see also">
134         <title>See Also</title>
135         <simplelist type="inline">
136             <member>
137                 <link linkend="pause">pause</link>
138             </member>
139             <member>
140                 <link linkend="halt">halt</link>
141             </member>
142         </simplelist>
143     </refsection>
144     <refsection role="history">
145         <title>History</title>
146         <revhistory>
147             <revision>
148                 <revnumber>6.0</revnumber>
149                 <revdescription>
150                     <itemizedlist>
151                         <listitem>
152                             The fractional part of <varname>milliseconds</varname>
153                             is now accepted and processed (replace xpause(microseconds)).
154                         </listitem>
155                         <listitem>Syntax sleep(seconds, "s") added.
156                         </listitem>
157                     </itemizedlist>
158                 </revdescription>
159             </revision>
160         </revhistory>
161     </refsection>
162 </refentry>
163