docs/reference/glib/tmpl/timers.sgml

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