glib/docs/gtimer.sgml

<!doctype chapter PUBLIC "-//Davenport//DTD DocBook V3.0//EN" []>
<chapter id="timer-functions">
  <docinfo>
    <title>Timer functions</title>
  </docinfo>
  <title>Timer functions</title>
  <sect1 id="timer-introduction">
    <title>Introduction</title>
    <para> </para>
    </sect1>
  <sect1 id="timers">
    <title>Timer functions</title>
    <para>This section describes the timer functions that are provided by 
    GLIB.</para>
      <sect2 id="g-timer-new">
	<title>g_timer_new</title>
	<funcsynopsis>
	  <funcdef>GTimer *<function>g_timer_new</function></funcdef>
	  <paramdef>void <parameter>(null) </parameter></paramdef>
	</funcsynopsis>
	<sect3><title>Description</title>
	  <para>Allocate a new timer and return the pointer to the newly 
          allocated timer structure. If enough resources are not available
	  for a new timer structure <type>NULL</type> will be returned.
	  This function will also start the timer once it has been allocated.
	  </para>
	</sect3>
	<sect3><title>Usage</title>
	  <programlisting role="C">
	    GTimer  *timer;
	    
	    timer = g_timer_new ();
	  </programlisting>
	</sect3>
	<sect3><title>Parameters</title>
	  <itemizedlist>
	    <listitem>
	      <para>void <parameter>(null)</parameter></para>
	      <para>This function takes no arguments</para>
	    </listitem>
	  </itemizedlist>
	</sect3>
      </sect2>
      <sect2 id="g-timer-destroy">
	<title>g_timer_destroy</title>
	<funcsynopsis>
	  <funcdef>void <function>g_timer_destroy</function></funcdef>
	  <paramdef>GTimer *<parameter>timer</parameter></paramdef>
	</funcsynopsis>
	<sect3><title>Description</title>
	  <para>This will destroy and free up the resources used by the 
          timer previously created with g_timer_new(). You should call this
          function when your done with the timer in question.</para>
	</sect3>
	<sect3><title>Usage</title>
	  <programlisting role="C">
	    GTimer   *timer;

	    timer = g_timer_new ();

	    /* do something useful with the timer */

	    g_timer_destroy (timer);
	  </programlisting>
	</sect3>
	<sect3><title>Parameters</title>
	  <para>GTimer *<parameter>timer</parameter></para>
	  <para>The pointer to the <type>GTimer</type> structre you wish to 
	    destroy.</para>
	  </sect3>
      </sect2>
      <sect2 id="g-timer-start">
	<title>g_timer_start</title>
	<funcsynopsis>
	  <funcdef>void <function>g_timer_start</function></funcdef>
	  <paramdef>GTimer *<parameter>timer</parameter></paramdef>
	</funcsynopsis>
	<sect3><title>Description</title>
	  <para>This will re-start the previously allocated timer running.
	  </para>
	</sect3>
	<sect3><title>Usage</title>
	  <programlisting role="C">
	    GTimer   *timer;

	    timer = g_timer_new ();
	    g_timer_stop (timer);

	    /* do stuff we don't want to time */

	    g_timer_start (timer);

	    /* do the stuff we want timed */

	  </programlisting>
	</sect3>
	<sect3><title>Parameters</title>
	  <para>GTimer *<parameter>timer</parameter></para>
	  <para>The timer to start that has been previously allocted with 
	    g_timer_new ();
	  </para>
	</sect3>
      </sect2>
      <sect2 id="g-timer-stop">
	<title>g_timer_stop</title>
	<funcsynopsis>
	  <funcdef>void <function>g_timer_stop</function></funcdef>
	  <paramdef> GTimer *<parameter>timer</parameter></paramdef>
	</funcsynopsis>
	<sect3><title>Description</title>
	  <para>This will stop a running timer.</para>
	</sect3>
	<sect3><title>Usage</title>
	  <programlisting role="C">
	    GTimer    *timer;

	    /* allocate and start new timer */
	    timer = g_timer_new ();

	    /* do anything you want timed with this timer */
	 
	    g_timer_stop (timer);     /* And stop the timer at the end */
	  </programlisting>
	</sect3>
	<sect3><title>Parameters</title>
	  <para>GTimer *<parameter>timer</parameter></para>
	  <para>A pointer to the previously allocated timer structre to
	    stop.</para>
	</sect3>
      </sect2>
      <sect2 id="g-timer-reset">
	<title>g_timer_reset</title>
	<funcsynopsis>
	  <funcdef>void <function>g_timer_reset</function></funcdef>
	  <paramdef>GTimer *<parameter>timer</parameter></paramdef>
	</funcsynopsis>
	<sect3><title>Description</title>
	  <para>Reset a previously allocated timer to prepare to time 
	    another sequence of events.</para>
	</sect3>
	<sect3><title>Usage</title>
	  <programlisting role="C">
	    GTimer   *timer;
	    
	    /* allocate a timer */
	    timer = g_timer_new ();
	    
	    /* timed function loop or what have you */
	    g_timer_stop (timer);
	    g_timer_reset (timer);
	    g_timer_start (timer);
	    /* loop here with a clean timer */

	    g_timer_destroy (timer);   /* done with the timer */
	  </programlisting>
	</sect3>
	<sect3><title>Parameters</title>
	  <para>GTimer *<parameter>timer</parameter></para>
	  <para>A pointer to a previously allocated timer structure.</para>
	</sect3>
      </sect2>
      <sect2 id="g-timer-elapsed">
	<title>g_timer_elapsed</title>
	<funcsynopsis>
	  <funcdef>gdouble <function>g_timer_elapsed</function></funcdef>
	  <paramdef>GTimer *<parameter>timer</parameter></paramdef>
	  <paramdef>gulong *<parameter>microseconds</parameter></paramdef>
	</funcsynopsis>
	<sect3><title>Description</title>
	  <para>Get the elapsed time between all g_timer_start() and the 
	    g_timer_stop() function calls. The return value of this function
	    is in seconds and the <parameter>microseconds</parameter> argument
	    will contain the microseconds value. If you are not intrested in
	    the microseconds value just pass a <type>NULL</type> as the 
	    second parameter.</para>
	  </sect3>
	<sect3><title>Usage</title>
	  <programlisting role="C">
	    GTimer    *timer
	    gdouble   seconds;
	    gulong    microseconds;

	    timer = g_timer_new ();
	    
	    /* do something that you want timed. */
	    
	    g_timer_stop (timer);

	    seconds = g_timer_elapsed (timer, \&microseconds);

	    g_print ("Elapsed time was %f seconds and %f microseconds\n",
	             seconds, microseconds);

	    g_timer_destroy (timer);
	  </programlisting>
	</sect3>
      </sect2>
    </sect1>
 </chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:("glib.sgml" "book" "sect1" "")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->