Home | History | Annotate | Download | only in tmpl 
      1 <!-- ##### SECTION Title ##### -->
      2 Timers
      3 
      4 <!-- ##### SECTION Short_Description ##### -->
      5 keep track of elapsed time
      6 
      7 <!-- ##### SECTION Long_Description ##### -->
      8 <para>
      9 #GTimer records a start time, and counts microseconds elapsed since that time.
     10 This is done somewhat differently on different platforms, and can be tricky to
     11 get exactly right, so #GTimer provides a portable/convenient interface.
     12 </para>
     13 <note><para>
     14 #GTimer uses a higher-quality clock when thread support is available. 
     15 Therefore, calling g_thread_init() while timers are running may lead to
     16 unreliable results. It is best to call g_thread_init() before starting
     17 any timers, if you are using threads at all.
     18 </para></note>
     19 
     20 <!-- ##### SECTION See_Also ##### -->
     21 <para>
     22 
     23 </para>
     24 
     25 <!-- ##### SECTION Stability_Level ##### -->
     26 
     27 
     28 <!-- ##### STRUCT GTimer ##### -->
     29 <para>
     30 Opaque datatype that records a start time. 
     31 </para>
     32 
     33 
     34 <!-- ##### FUNCTION g_timer_new ##### -->
     35 <para>
     36 Creates a new timer, and starts timing (i.e. g_timer_start() is implicitly
     37 called for you).
     38 </para>
     39 
     40 @Returns: a new #GTimer.
     41 
     42 
     43 <!-- ##### FUNCTION g_timer_start ##### -->
     44 <para>
     45 Marks a start time, so that future calls to g_timer_elapsed() will report the
     46 time since g_timer_start() was called. g_timer_new() automatically marks the
     47 start time, so no need to call g_timer_start() immediately after creating the
     48 timer.
     49 </para>
     50 
     51 @timer: a #GTimer.
     52 
     53 
     54 <!-- ##### FUNCTION g_timer_stop ##### -->
     55 <para>
     56 Marks an end time, so calls to g_timer_elapsed() will return the difference
     57 between this end time and the start time.
     58 </para>
     59 
     60 @timer: a #GTimer.
     61 
     62 
     63 <!-- ##### FUNCTION g_timer_continue ##### -->
     64 <para>
     65 Resumes a timer that has previously been stopped with g_timer_stop().
     66 g_timer_stop() must be called before using this function.
     67 </para>
     68 
     69 @timer: a #GTimer.
     70 @Since: 2.4
     71 
     72 
     73 <!-- ##### FUNCTION g_timer_elapsed ##### -->
     74 <para>
     75 If @timer has been started but not stopped, obtains the time since the timer was
     76 started. If @timer has been stopped, obtains the elapsed time between the time
     77 it was started and the time it was stopped. The return value is the number of
     78 seconds elapsed, including any fractional part. The @microseconds
     79 out parameter is essentially useless.
     80 <warning><para>Calling initialization functions, in particular g_thread_init(),
     81 while a timer is running will cause invalid return values from this function.
     82 </para></warning>
     83 </para>
     84 
     85 @timer: a #GTimer.
     86 @microseconds: return location for the fractional part of seconds elapsed, 
     87   in microseconds (that is, the total number of microseconds elapsed, modulo 
     88    1000000), or %NULL
     89 @Returns: seconds elapsed as a floating point value, including 
     90   any fractional part.
     91 
     92 
     93 <!-- ##### FUNCTION g_timer_reset ##### -->
     94 <para>
     95 This function is useless; it's fine to call g_timer_start() on an
     96 already-started timer to reset the start time, so g_timer_reset() serves no
     97 purpose.
     98 </para>
     99 
    100 @timer: a #GTimer.
    101 
    102 
    103 <!-- ##### FUNCTION g_timer_destroy ##### -->
    104 <para>
    105 Destroys a timer, freeing associated resources.
    106 </para>
    107 
    108 @timer: a #GTimer to destroy.
    109 
    110 
    111