<refentry id="glib-Timers">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Timers.top_of_page">Timers</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Timers</refname>
<refpurpose>keep track of elapsed time</refpurpose>
</refnamediv>

<refsynopsisdiv id="glib-Timers.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

                    <link linkend="GTimer">GTimer</link>;
<link linkend="GTimer">GTimer</link>*             <link linkend="g-timer-new">g_timer_new</link>                         (void);
<link linkend="void">void</link>                <link linkend="g-timer-start">g_timer_start</link>                       (<link linkend="GTimer">GTimer</link> *timer);
<link linkend="void">void</link>                <link linkend="g-timer-stop">g_timer_stop</link>                        (<link linkend="GTimer">GTimer</link> *timer);
<link linkend="void">void</link>                <link linkend="g-timer-continue">g_timer_continue</link>                    (<link linkend="GTimer">GTimer</link> *timer);
<link linkend="gdouble">gdouble</link>             <link linkend="g-timer-elapsed">g_timer_elapsed</link>                     (<link linkend="GTimer">GTimer</link> *timer,
                                                         <link linkend="gulong">gulong</link> *microseconds);
<link linkend="void">void</link>                <link linkend="g-timer-reset">g_timer_reset</link>                       (<link linkend="GTimer">GTimer</link> *timer);
<link linkend="void">void</link>                <link linkend="g-timer-destroy">g_timer_destroy</link>                     (<link linkend="GTimer">GTimer</link> *timer);
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-Timers.description" role="desc">
<title role="desc.title">Description</title>
<para>
<link linkend="GTimer"><type>GTimer</type></link> records a start time, and counts microseconds elapsed since that time.
This is done somewhat differently on different platforms, and can be tricky to
get exactly right, so <link linkend="GTimer"><type>GTimer</type></link> provides a portable/convenient interface.
</para>
<note><para>
<link linkend="GTimer"><type>GTimer</type></link> uses a higher-quality clock when thread support is available.
Therefore, calling <link linkend="g-thread-init"><function>g_thread_init()</function></link> while timers are running may lead to
unreliable results. It is best to call <link linkend="g-thread-init"><function>g_thread_init()</function></link> before starting
any timers, if you are using threads at all.
</para></note>
</refsect1>

<refsect1 id="glib-Timers.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GTimer" role="struct">
<title>GTimer</title>
<indexterm zone="GTimer"><primary sortas="Timer">GTimer</primary></indexterm><programlisting>typedef struct _GTimer GTimer;</programlisting>
<para>
Opaque datatype that records a start time.
</para></refsect2>
<refsect2 id="g-timer-new" role="function">
<title>g_timer_new ()</title>
<indexterm zone="g-timer-new"><primary sortas="timer_new">g_timer_new</primary></indexterm><programlisting><link linkend="GTimer">GTimer</link>*             g_timer_new                         (void);</programlisting>
<para>
Creates a new timer, and starts timing (i.e. <link linkend="g-timer-start"><function>g_timer_start()</function></link> is implicitly
called for you).
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a new <link linkend="GTimer"><type>GTimer</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-timer-start" role="function">
<title>g_timer_start ()</title>
<indexterm zone="g-timer-start"><primary sortas="timer_start">g_timer_start</primary></indexterm><programlisting><link linkend="void">void</link>                g_timer_start                       (<link linkend="GTimer">GTimer</link> *timer);</programlisting>
<para>
Marks a start time, so that future calls to <link linkend="g-timer-elapsed"><function>g_timer_elapsed()</function></link> will report the
time since <link linkend="g-timer-start"><function>g_timer_start()</function></link> was called. <link linkend="g-timer-new"><function>g_timer_new()</function></link> automatically marks the
start time, so no need to call <link linkend="g-timer-start"><function>g_timer_start()</function></link> immediately after creating the
timer.
</para><variablelist role="params">
<varlistentry><term><parameter>timer</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GTimer"><type>GTimer</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-timer-stop" role="function">
<title>g_timer_stop ()</title>
<indexterm zone="g-timer-stop"><primary sortas="timer_stop">g_timer_stop</primary></indexterm><programlisting><link linkend="void">void</link>                g_timer_stop                        (<link linkend="GTimer">GTimer</link> *timer);</programlisting>
<para>
Marks an end time, so calls to <link linkend="g-timer-elapsed"><function>g_timer_elapsed()</function></link> will return the difference
between this end time and the start time.
</para><variablelist role="params">
<varlistentry><term><parameter>timer</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GTimer"><type>GTimer</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-timer-continue" role="function" condition="since:2.4">
<title>g_timer_continue ()</title>
<indexterm zone="g-timer-continue" role="2.4"><primary sortas="timer_continue">g_timer_continue</primary></indexterm><programlisting><link linkend="void">void</link>                g_timer_continue                    (<link linkend="GTimer">GTimer</link> *timer);</programlisting>
<para>
Resumes a timer that has previously been stopped with <link linkend="g-timer-stop"><function>g_timer_stop()</function></link>.
<link linkend="g-timer-stop"><function>g_timer_stop()</function></link> must be called before using this function.
</para><variablelist role="params">
<varlistentry><term><parameter>timer</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GTimer"><type>GTimer</type></link>.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-timer-elapsed" role="function">
<title>g_timer_elapsed ()</title>
<indexterm zone="g-timer-elapsed"><primary sortas="timer_elapsed">g_timer_elapsed</primary></indexterm><programlisting><link linkend="gdouble">gdouble</link>             g_timer_elapsed                     (<link linkend="GTimer">GTimer</link> *timer,
                                                         <link linkend="gulong">gulong</link> *microseconds);</programlisting>
<para>
If <parameter>timer</parameter> has been started but not stopped, obtains the time since the timer was
started. If <parameter>timer</parameter> has been stopped, obtains the elapsed time between the time
it was started and the time it was stopped. The return value is the number of
seconds elapsed, including any fractional part. The <parameter>microseconds</parameter>
out parameter is essentially useless.
<warning><para>Calling initialization functions, in particular <link linkend="g-thread-init"><function>g_thread_init()</function></link>,
while a timer is running will cause invalid return values from this function.
</para></warning>
</para><variablelist role="params">
<varlistentry><term><parameter>timer</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GTimer"><type>GTimer</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>microseconds</parameter>&#160;:</term>
<listitem><simpara>return location for the fractional part of seconds elapsed, 
  in microseconds (that is, the total number of microseconds elapsed, modulo
   1000000), or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>seconds elapsed as a floating point value, including 
  any fractional part.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-timer-reset" role="function">
<title>g_timer_reset ()</title>
<indexterm zone="g-timer-reset"><primary sortas="timer_reset">g_timer_reset</primary></indexterm><programlisting><link linkend="void">void</link>                g_timer_reset                       (<link linkend="GTimer">GTimer</link> *timer);</programlisting>
<para>
This function is useless; it's fine to call <link linkend="g-timer-start"><function>g_timer_start()</function></link> on an
already-started timer to reset the start time, so <link linkend="g-timer-reset"><function>g_timer_reset()</function></link> serves no
purpose.
</para><variablelist role="params">
<varlistentry><term><parameter>timer</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GTimer"><type>GTimer</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-timer-destroy" role="function">
<title>g_timer_destroy ()</title>
<indexterm zone="g-timer-destroy"><primary sortas="timer_destroy">g_timer_destroy</primary></indexterm><programlisting><link linkend="void">void</link>                g_timer_destroy                     (<link linkend="GTimer">GTimer</link> *timer);</programlisting>
<para>
Destroys a timer, freeing associated resources.
</para><variablelist role="params">
<varlistentry><term><parameter>timer</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GTimer"><type>GTimer</type></link> to destroy.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
