From f6482a1eaa10f6e21536776ca667980ccd9e5f77 Mon Sep 17 00:00:00 2001 From: Ryan Lortie Date: Sat, 30 Jan 2010 22:12:22 -0500 Subject: [PATCH] GTimer: move docs from tmpl to .c --- docs/reference/glib/tmpl/.gitignore | 1 + docs/reference/glib/tmpl/timers.sgml | 110 --------------------------- glib/gtimer.c | 91 +++++++++++++++++++++- 3 files changed, 91 insertions(+), 111 deletions(-) delete mode 100644 docs/reference/glib/tmpl/timers.sgml diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore index 9cd641561..1edcd06ae 100644 --- a/docs/reference/glib/tmpl/.gitignore +++ b/docs/reference/glib/tmpl/.gitignore @@ -6,3 +6,4 @@ hash_tables.sgml option.sgml random_numbers.sgml threads.sgml +timers.sgml diff --git a/docs/reference/glib/tmpl/timers.sgml b/docs/reference/glib/tmpl/timers.sgml deleted file mode 100644 index 8e3cfa806..000000000 --- a/docs/reference/glib/tmpl/timers.sgml +++ /dev/null @@ -1,110 +0,0 @@ - -Timers - - -keep track of elapsed time - - - -#GTimer 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 #GTimer provides a portable/convenient interface. - - -#GTimer uses a higher-quality clock when thread support is available. -Therefore, calling g_thread_init() while timers are running may lead to -unreliable results. It is best to call g_thread_init() before starting -any timers, if you are using threads at all. - - - - - - - - - - - - -Opaque datatype that records a start time. - - - - - -Creates a new timer, and starts timing (i.e. g_timer_start() is implicitly -called for you). - - -@Returns: a new #GTimer. - - - - -Marks a start time, so that future calls to g_timer_elapsed() will report the -time since g_timer_start() was called. g_timer_new() automatically marks the -start time, so no need to call g_timer_start() immediately after creating the -timer. - - -@timer: a #GTimer. - - - - -Marks an end time, so calls to g_timer_elapsed() will return the difference -between this end time and the start time. - - -@timer: a #GTimer. - - - - -Resumes a timer that has previously been stopped with g_timer_stop(). -g_timer_stop() must be called before using this function. - - -@timer: a #GTimer. -@Since: 2.4 - - - - -If @timer has been started but not stopped, obtains the time since the timer was -started. If @timer 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 @microseconds -out parameter is essentially useless. -Calling initialization functions, in particular g_thread_init(), -while a timer is running will cause invalid return values from this function. - - - -@timer: a #GTimer. -@microseconds: return location for the fractional part of seconds elapsed, - in microseconds (that is, the total number of microseconds elapsed, modulo - 1000000), or %NULL -@Returns: seconds elapsed as a floating point value, including - any fractional part. - - - - -This function is useless; it's fine to call g_timer_start() on an -already-started timer to reset the start time, so g_timer_reset() serves no -purpose. - - -@timer: a #GTimer. - - - - -Destroys a timer, freeing associated resources. - - -@timer: a #GTimer to destroy. - - diff --git a/glib/gtimer.c b/glib/gtimer.c index cd6a082c5..4e8397cb5 100644 --- a/glib/gtimer.c +++ b/glib/gtimer.c @@ -51,10 +51,33 @@ #include "gthread.h" #include "galias.h" +/** + * SECTION: timers + * @title: Timers + * @short_description: keep track of elapsed time + * + * #GTimer 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 #GTimer provides a + * portable/convenient interface. + * + * + * #GTimer uses a higher-quality clock when thread support is available. + * Therefore, calling g_thread_init() while timers are running may lead to + * unreliable results. It is best to call g_thread_init() before starting any + * timers, if you are using threads at all. + * + **/ + #define G_NSEC_PER_SEC 1000000000 #define GETTIME(v) (v = g_thread_gettime ()) +/** + * GTimer: + * + * Opaque datatype that records a start time. + **/ struct _GTimer { guint64 start; @@ -63,7 +86,13 @@ struct _GTimer guint active : 1; }; - +/** + * g_timer_new: + * @Returns: a new #GTimer. + * + * Creates a new timer, and starts timing (i.e. g_timer_start() is + * implicitly called for you). + **/ GTimer* g_timer_new (void) { @@ -77,6 +106,12 @@ g_timer_new (void) return timer; } +/** + * g_timer_destroy: + * @timer: a #GTimer to destroy. + * + * Destroys a timer, freeing associated resources. + **/ void g_timer_destroy (GTimer *timer) { @@ -85,6 +120,15 @@ g_timer_destroy (GTimer *timer) g_free (timer); } +/** + * g_timer_start: + * @timer: a #GTimer. + * + * Marks a start time, so that future calls to g_timer_elapsed() will + * report the time since g_timer_start() was called. g_timer_new() + * automatically marks the start time, so no need to call + * g_timer_start() immediately after creating the timer. + **/ void g_timer_start (GTimer *timer) { @@ -95,6 +139,13 @@ g_timer_start (GTimer *timer) GETTIME (timer->start); } +/** + * g_timer_stop: + * @timer: a #GTimer. + * + * Marks an end time, so calls to g_timer_elapsed() will return the + * difference between this end time and the start time. + **/ void g_timer_stop (GTimer *timer) { @@ -105,6 +156,14 @@ g_timer_stop (GTimer *timer) GETTIME (timer->end); } +/** + * g_timer_reset: + * @timer: a #GTimer. + * + * This function is useless; it's fine to call g_timer_start() on an + * already-started timer to reset the start time, so g_timer_reset() + * serves no purpose. + **/ void g_timer_reset (GTimer *timer) { @@ -113,6 +172,15 @@ g_timer_reset (GTimer *timer) GETTIME (timer->start); } +/** + * g_timer_continue: + * @timer: a #GTimer. + * @Since: 2.4 + * + * Resumes a timer that has previously been stopped with + * g_timer_stop(). g_timer_stop() must be called before using this + * function. + **/ void g_timer_continue (GTimer *timer) { @@ -135,6 +203,27 @@ g_timer_continue (GTimer *timer) timer->active = TRUE; } +/** + * g_timer_elapsed: + * @timer: a #GTimer. + * @microseconds: return location for the fractional part of seconds + * elapsed, in microseconds (that is, the total number + * of microseconds elapsed, modulo 1000000), or %NULL + * @Returns: seconds elapsed as a floating point value, including any + * fractional part. + * + * If @timer has been started but not stopped, obtains the time since + * the timer was started. If @timer 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 @microseconds out parameter is + * essentially useless. + * + * + * Calling initialization functions, in particular g_thread_init(), while a + * timer is running will cause invalid return values from this function. + * + **/ gdouble g_timer_elapsed (GTimer *timer, gulong *microseconds)