docs/reference/glib/html/glib-Timers.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Timers</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="index.html" title="GLib Reference Manual">
   8 <link rel="up" href="glib-utilities.html" title="GLib Utilities">
   9 <link rel="prev" href="glib-Automatic-String-Completion.html" title="Automatic String Completion">
  10 <link rel="next" href="glib-Spawning-Processes.html" title="Spawning Processes">
  11 <meta name="generator" content="GTK-Doc V1.13 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 <link rel="chapter" href="glib.html" title="GLib Overview">
  14 <link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals">
  15 <link rel="chapter" href="glib-core.html" title="GLib Core Application Support">
  16 <link rel="chapter" href="glib-utilities.html" title="GLib Utilities">
  17 <link rel="chapter" href="glib-data-types.html" title="GLib Data Types">
  18 <link rel="chapter" href="tools.html" title="GLib Tools">
  19 <link rel="index" href="api-index-full.html" title="Index">
  20 <link rel="index" href="api-index-deprecated.html" title="Index of deprecated symbols">
  21 <link rel="index" href="api-index-2-2.html" title="Index of new symbols in 2.2">
  22 <link rel="index" href="api-index-2-4.html" title="Index of new symbols in 2.4">
  23 <link rel="index" href="api-index-2-6.html" title="Index of new symbols in 2.6">
  24 <link rel="index" href="api-index-2-8.html" title="Index of new symbols in 2.8">
  25 <link rel="index" href="api-index-2-10.html" title="Index of new symbols in 2.10">
  26 <link rel="index" href="api-index-2-12.html" title="Index of new symbols in 2.12">
  27 <link rel="index" href="api-index-2-14.html" title="Index of new symbols in 2.14">
  28 <link rel="index" href="api-index-2-16.html" title="Index of new symbols in 2.16">
  29 <link rel="index" href="api-index-2-18.html" title="Index of new symbols in 2.18">
  30 <link rel="index" href="api-index-2-20.html" title="Index of new symbols in 2.20">
  31 <link rel="index" href="api-index-2-22.html" title="Index of new symbols in 2.22">
  32 <link rel="index" href="api-index-2-24.html" title="Index of new symbols in 2.24">
  33 </head>
  34 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  35 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  36 <tr valign="middle">
  37 <td><a accesskey="p" href="glib-Automatic-String-Completion.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  38 <td><a accesskey="u" href="glib-utilities.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  39 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  40 <th width="100%" align="center">GLib Reference Manual</th>
  41 <td><a accesskey="n" href="glib-Spawning-Processes.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  42 </tr>
  43 <tr><td colspan="5" class="shortcuts">
  44 <a href="#glib-Timers.synopsis" class="shortcut">Top</a>
  45                    |
  46                   <a href="#glib-Timers.description" class="shortcut">Description</a>
  47 </td></tr>
  48 </table>
  49 <div class="refentry" title="Timers">
  50 <a name="glib-Timers"></a><div class="titlepage"></div>
  51 <div class="refnamediv"><table width="100%"><tr>
  52 <td valign="top">
  53 <h2><span class="refentrytitle"><a name="glib-Timers.top_of_page"></a>Timers</span></h2>
  54 <p>Timers — keep track of elapsed time</p>
  55 </td>
  56 <td valign="top" align="right"></td>
  57 </tr></table></div>
  58 <div class="refsynopsisdiv" title="Synopsis">
  59 <a name="glib-Timers.synopsis"></a><h2>Synopsis</h2>
  60 <pre class="synopsis">
  61 #include &lt;glib.h&gt;
  62
  63                     <a class="link" href="glib-Timers.html#GTimer" title="GTimer">GTimer</a>;
  64 <a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="returnvalue">GTimer</span></a>*             <a class="link" href="glib-Timers.html#g-timer-new" title="g_timer_new ()">g_timer_new</a>                         (void);
  65 <span class="returnvalue">void</span>                <a class="link" href="glib-Timers.html#g-timer-start" title="g_timer_start ()">g_timer_start</a>                       (<a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="returnvalue">GTimer</span></a> *timer);
  66 <span class="returnvalue">void</span>                <a class="link" href="glib-Timers.html#g-timer-stop" title="g_timer_stop ()">g_timer_stop</a>                        (<a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="returnvalue">GTimer</span></a> *timer);
  67 <span class="returnvalue">void</span>                <a class="link" href="glib-Timers.html#g-timer-continue" title="g_timer_continue ()">g_timer_continue</a>                    (<a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="returnvalue">GTimer</span></a> *timer);
  68 <a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="returnvalue">gdouble</span></a>             <a class="link" href="glib-Timers.html#g-timer-elapsed" title="g_timer_elapsed ()">g_timer_elapsed</a>                     (<a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="returnvalue">GTimer</span></a> *timer,
  69                                                          <a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="returnvalue">gulong</span></a> *microseconds);
  70 <span class="returnvalue">void</span>                <a class="link" href="glib-Timers.html#g-timer-reset" title="g_timer_reset ()">g_timer_reset</a>                       (<a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="returnvalue">GTimer</span></a> *timer);
  71 <span class="returnvalue">void</span>                <a class="link" href="glib-Timers.html#g-timer-destroy" title="g_timer_destroy ()">g_timer_destroy</a>                     (<a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="returnvalue">GTimer</span></a> *timer);
  72 </pre>
  73 </div>
  74 <div class="refsect1" title="Description">
  75 <a name="glib-Timers.description"></a><h2>Description</h2>
  76 <p>
  77 <a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="type">GTimer</span></a> records a start time, and counts microseconds elapsed since
  78 that time. This is done somewhat differently on different platforms,
  79 and can be tricky to get exactly right, so <a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="type">GTimer</span></a> provides a
  80 portable/convenient interface.
  81 </p>
  82 <p>
  83 </p>
  84 <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
  85 <h3 class="title">Note</h3>
  86 <p>
  87  <a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="type">GTimer</span></a> uses a higher-quality clock when thread support is available.
  88  Therefore, calling <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> while timers are running may lead to
  89  unreliable results. It is best to call <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> before starting any
  90  timers, if you are using threads at all.
  91 </p>
  92 </div>
  93 </div>
  94 <div class="refsect1" title="Details">
  95 <a name="glib-Timers.details"></a><h2>Details</h2>
  96 <div class="refsect2" title="GTimer">
  97 <a name="GTimer"></a><h3>GTimer</h3>
  98 <pre class="programlisting">typedef struct _GTimer GTimer;</pre>
  99 <p>
 100 Opaque datatype that records a start time.</p>
 101 </div>
 102 <hr>
 103 <div class="refsect2" title="g_timer_new ()">
 104 <a name="g-timer-new"></a><h3>g_timer_new ()</h3>
 105 <pre class="programlisting"><a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="returnvalue">GTimer</span></a>*             g_timer_new                         (void);</pre>
 106 <p>
 107 Creates a new timer, and starts timing (i.e. <a class="link" href="glib-Timers.html#g-timer-start" title="g_timer_start ()"><code class="function">g_timer_start()</code></a> is
 108 implicitly called for you).</p>
 109 <div class="variablelist"><table border="0">
 110 <col align="left" valign="top">
 111 <tbody><tr>
 112 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 113 <td> a new <a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="type">GTimer</span></a>.
 114 </td>
 115 </tr></tbody>
 116 </table></div>
 117 </div>
 118 <hr>
 119 <div class="refsect2" title="g_timer_start ()">
 120 <a name="g-timer-start"></a><h3>g_timer_start ()</h3>
 121 <pre class="programlisting"><span class="returnvalue">void</span>                g_timer_start                       (<a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="returnvalue">GTimer</span></a> *timer);</pre>
 122 <p>
 123 Marks a start time, so that future calls to <a class="link" href="glib-Timers.html#g-timer-elapsed" title="g_timer_elapsed ()"><code class="function">g_timer_elapsed()</code></a> will
 124 report the time since <a class="link" href="glib-Timers.html#g-timer-start" title="g_timer_start ()"><code class="function">g_timer_start()</code></a> was called. <a class="link" href="glib-Timers.html#g-timer-new" title="g_timer_new ()"><code class="function">g_timer_new()</code></a>
 125 automatically marks the start time, so no need to call
 126 <a class="link" href="glib-Timers.html#g-timer-start" title="g_timer_start ()"><code class="function">g_timer_start()</code></a> immediately after creating the timer.</p>
 127 <div class="variablelist"><table border="0">
 128 <col align="left" valign="top">
 129 <tbody><tr>
 130 <td><p><span class="term"><em class="parameter"><code>timer</code></em> :</span></p></td>
 131 <td> a <a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="type">GTimer</span></a>.
 132 </td>
 133 </tr></tbody>
 134 </table></div>
 135 </div>
 136 <hr>
 137 <div class="refsect2" title="g_timer_stop ()">
 138 <a name="g-timer-stop"></a><h3>g_timer_stop ()</h3>
 139 <pre class="programlisting"><span class="returnvalue">void</span>                g_timer_stop                        (<a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="returnvalue">GTimer</span></a> *timer);</pre>
 140 <p>
 141 Marks an end time, so calls to <a class="link" href="glib-Timers.html#g-timer-elapsed" title="g_timer_elapsed ()"><code class="function">g_timer_elapsed()</code></a> will return the
 142 difference between this end time and the start time.</p>
 143 <div class="variablelist"><table border="0">
 144 <col align="left" valign="top">
 145 <tbody><tr>
 146 <td><p><span class="term"><em class="parameter"><code>timer</code></em> :</span></p></td>
 147 <td> a <a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="type">GTimer</span></a>.
 148 </td>
 149 </tr></tbody>
 150 </table></div>
 151 </div>
 152 <hr>
 153 <div class="refsect2" title="g_timer_continue ()">
 154 <a name="g-timer-continue"></a><h3>g_timer_continue ()</h3>
 155 <pre class="programlisting"><span class="returnvalue">void</span>                g_timer_continue                    (<a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="returnvalue">GTimer</span></a> *timer);</pre>
 156 <p>
 157 Resumes a timer that has previously been stopped with
 158 <a class="link" href="glib-Timers.html#g-timer-stop" title="g_timer_stop ()"><code class="function">g_timer_stop()</code></a>. <a class="link" href="glib-Timers.html#g-timer-stop" title="g_timer_stop ()"><code class="function">g_timer_stop()</code></a> must be called before using this
 159 function.</p>
 160 <div class="variablelist"><table border="0">
 161 <col align="left" valign="top">
 162 <tbody><tr>
 163 <td><p><span class="term"><em class="parameter"><code>timer</code></em> :</span></p></td>
 164 <td> a <a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="type">GTimer</span></a>.
 165 </td>
 166 </tr></tbody>
 167 </table></div>
 168 <p class="since">Since 2.4</p>
 169 </div>
 170 <hr>
 171 <div class="refsect2" title="g_timer_elapsed ()">
 172 <a name="g-timer-elapsed"></a><h3>g_timer_elapsed ()</h3>
 173 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="returnvalue">gdouble</span></a>             g_timer_elapsed                     (<a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="returnvalue">GTimer</span></a> *timer,
 174                                                          <a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="returnvalue">gulong</span></a> *microseconds);</pre>
 175 <p>
 176 If <em class="parameter"><code>timer</code></em> has been started but not stopped, obtains the time since
 177 the timer was started. If <em class="parameter"><code>timer</code></em> has been stopped, obtains the
 178 elapsed time between the time it was started and the time it was
 179 stopped. The return value is the number of seconds elapsed,
 180 including any fractional part. The <em class="parameter"><code>microseconds</code></em> out parameter is
 181 essentially useless.
 182 </p>
 183 <p>
 184 </p>
 185 <div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 186 <h3 class="title">Warning</h3>
 187 <p>
 188  Calling initialization functions, in particular <a class="link" href="glib-Threads.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a>, while a
 189  timer is running will cause invalid return values from this function.
 190 </p>
 191 </div>
 192 <div class="variablelist"><table border="0">
 193 <col align="left" valign="top">
 194 <tbody>
 195 <tr>
 196 <td><p><span class="term"><em class="parameter"><code>timer</code></em> :</span></p></td>
 197 <td> a <a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="type">GTimer</span></a>.
 198 </td>
 199 </tr>
 200 <tr>
 201 <td><p><span class="term"><em class="parameter"><code>microseconds</code></em> :</span></p></td>
 202 <td> return location for the fractional part of seconds
 203                elapsed, in microseconds (that is, the total number
 204                of microseconds elapsed, modulo 1000000), or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
 205 </td>
 206 </tr>
 207 <tr>
 208 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 209 <td> seconds elapsed as a floating point value, including any
 210           fractional part.
 211 </td>
 212 </tr>
 213 </tbody>
 214 </table></div>
 215 </div>
 216 <hr>
 217 <div class="refsect2" title="g_timer_reset ()">
 218 <a name="g-timer-reset"></a><h3>g_timer_reset ()</h3>
 219 <pre class="programlisting"><span class="returnvalue">void</span>                g_timer_reset                       (<a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="returnvalue">GTimer</span></a> *timer);</pre>
 220 <p>
 221 This function is useless; it's fine to call <a class="link" href="glib-Timers.html#g-timer-start" title="g_timer_start ()"><code class="function">g_timer_start()</code></a> on an
 222 already-started timer to reset the start time, so <a class="link" href="glib-Timers.html#g-timer-reset" title="g_timer_reset ()"><code class="function">g_timer_reset()</code></a>
 223 serves no purpose.</p>
 224 <div class="variablelist"><table border="0">
 225 <col align="left" valign="top">
 226 <tbody><tr>
 227 <td><p><span class="term"><em class="parameter"><code>timer</code></em> :</span></p></td>
 228 <td> a <a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="type">GTimer</span></a>.
 229 </td>
 230 </tr></tbody>
 231 </table></div>
 232 </div>
 233 <hr>
 234 <div class="refsect2" title="g_timer_destroy ()">
 235 <a name="g-timer-destroy"></a><h3>g_timer_destroy ()</h3>
 236 <pre class="programlisting"><span class="returnvalue">void</span>                g_timer_destroy                     (<a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="returnvalue">GTimer</span></a> *timer);</pre>
 237 <p>
 238 Destroys a timer, freeing associated resources.</p>
 239 <div class="variablelist"><table border="0">
 240 <col align="left" valign="top">
 241 <tbody><tr>
 242 <td><p><span class="term"><em class="parameter"><code>timer</code></em> :</span></p></td>
 243 <td> a <a class="link" href="glib-Timers.html#GTimer" title="GTimer"><span class="type">GTimer</span></a> to destroy.
 244 </td>
 245 </tr></tbody>
 246 </table></div>
 247 </div>
 248 </div>
 249 </div>
 250 <div class="footer">
 251 <hr>
 252           Generated by GTK-Doc V1.13</div>
 253 </body>
 254 </html>