[glib] GTimer: move docs from tmpl to .c
- From: Ryan Lortie <ryanl src gnome org>
- To: svn-commits-list gnome org
- Cc:
- Subject: [glib] GTimer: move docs from tmpl to .c
- Date: Sun, 31 Jan 2010 03:12:53 +0000 (UTC)
commit f6482a1eaa10f6e21536776ca667980ccd9e5f77
Author: Ryan Lortie <desrt desrt ca>
Date: Sat Jan 30 22:12:22 2010 -0500
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(-)
---
diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore
index 9cd6415..1edcd06 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/glib/gtimer.c b/glib/gtimer.c
index cd6a082..4e8397c 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.
+ *
+ * <note><para>
+ * #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.
+ * </para></note>
+ **/
+
#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.
+ *
+ * <warning><para>
+ * Calling initialization functions, in particular g_thread_init(), while a
+ * timer is running will cause invalid return values from this function.
+ * </para></warning>
+ **/
gdouble
g_timer_elapsed (GTimer *timer,
gulong *microseconds)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]