timers.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<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 &lt;glib.h&gt;


struct      <link linkend="GTimer">GTimer</link>;
<link linkend="GTimer">GTimer</link>*     <link linkend="g-timer-new">g_timer_new</link>                     (void);
void        <link linkend="g-timer-start">g_timer_start</link>                   (<link linkend="GTimer">GTimer</link> *timer);
void        <link linkend="g-timer-stop">g_timer_stop</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);
void        <link linkend="g-timer-reset">g_timer_reset</link>                   (<link linkend="GTimer">GTimer</link> *timer);
void        <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">GTimer</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">GTimer</link> provides a portable/convenient interface.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GTimer">struct GTimer</title>
<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>
<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">g_timer_start</link>() is implicitly
called for you).
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a new <link linkend="GTimer">GTimer</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-timer-start">g_timer_start ()</title>
<programlisting>void        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">g_timer_elapsed</link>() will report the
time since <link linkend="g-timer-start">g_timer_start</link>() was called. <link linkend="g-timer-new">g_timer_new</link>() automatically marks the
start time, so no need to call <link linkend="g-timer-start">g_timer_start</link>() immediately after creating the
timer.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>timer</parameter>&nbsp;:</entry>
<entry>a <link linkend="GTimer">GTimer</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-timer-stop">g_timer_stop ()</title>
<programlisting>void        g_timer_stop                    (<link linkend="GTimer">GTimer</link> *timer);</programlisting>
<para>
Marks an end time, so calls to <link linkend="g-timer-elapsed">g_timer_elapsed</link>() will return the difference
between this end time and the start time.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>timer</parameter>&nbsp;:</entry>
<entry>a <link linkend="GTimer">GTimer</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-timer-elapsed">g_timer_elapsed ()</title>
<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, and the <parameter>microseconds</parameter> argument allows you to get the number of
microseconds.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>timer</parameter>&nbsp;:</entry>
<entry>a <link linkend="GTimer">GTimer</link>.
</entry></row>
<row><entry align="right"><parameter>microseconds</parameter>&nbsp;:</entry>
<entry>return location for microseconds elapsed, or <literal>NULL</literal>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>seconds elapsed.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-timer-reset">g_timer_reset ()</title>
<programlisting>void        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">g_timer_start</link>() on an
already-started timer to reset the start time, so <link linkend="g-timer-reset">g_timer_reset</link>() serves no
purpose.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>timer</parameter>&nbsp;:</entry>
<entry>a <link linkend="GTimer">GTimer</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-timer-destroy">g_timer_destroy ()</title>
<programlisting>void        g_timer_destroy                 (<link linkend="GTimer">GTimer</link> *timer);</programlisting>
<para>
Destroys a timer, freeing associated resources.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>timer</parameter>&nbsp;:</entry>
<entry>a <link linkend="GTimer">GTimer</link> to destroy.


</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>