<refentry id="glib-Timers">
<refmeta>
<refentrytitle>Timers</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Timers</refname><refpurpose>
keep track of elapsed time.</refpurpose>
</refnamediv>
<refsynopsisdiv><title>Synopsis</title>
<synopsis>
#include <glib.h>
struct <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>
<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>
</refsect1>
<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GTimer"/>struct GTimer</title>
<indexterm><primary>GTimer</primary></indexterm><programlisting>struct GTimer;</programlisting>
<para>
Opaque datatype that records a start time.
</para></refsect2>
<refsect2>
<title><anchor id="g-timer-new"/>g_timer_new ()</title>
<indexterm><primary>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> :</term><listitem><simpara>a new <link linkend="GTimer"><type>GTimer</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-timer-start"/>g_timer_start ()</title>
<indexterm><primary>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> :</term>
<listitem><simpara>a <link linkend="GTimer"><type>GTimer</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-timer-stop"/>g_timer_stop ()</title>
<indexterm><primary>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> :</term>
<listitem><simpara>a <link linkend="GTimer"><type>GTimer</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-timer-continue"/>g_timer_continue ()</title>
<indexterm role="2.4"><primary>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> :</term>
<listitem><simpara>a <link linkend="GTimer"><type>GTimer</type></link>.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4
</para></refsect2>
<refsect2>
<title><anchor id="g-timer-elapsed"/>g_timer_elapsed ()</title>
<indexterm><primary>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.
</para><variablelist role="params">
<varlistentry><term><parameter>timer</parameter> :</term>
<listitem><simpara>a <link linkend="GTimer"><type>GTimer</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>microseconds</parameter> :</term>
<listitem><simpara>fractional part of seconds elapsed, in microseconds
(that is, the total number of microseconds elapsed, modulo
1000000)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>seconds elapsed as a floating point value, including
any fractional part.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-timer-reset"/>g_timer_reset ()</title>
<indexterm><primary>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> :</term>
<listitem><simpara>a <link linkend="GTimer"><type>GTimer</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-timer-destroy"/>g_timer_destroy ()</title>
<indexterm><primary>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> :</term>
<listitem><simpara>a <link linkend="GTimer"><type>GTimer</type></link> to destroy.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
</refentry>