luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-10 19:36:18 +01:00
Code Issues Packages Projects Releases Wiki Activity

GTimer: move docs from tmpl to .c

Browse Source
This commit is contained in:
Ryan Lortie 2010-01-30 22:12:22 -05:00
parent d87712d3e6
commit f6482a1eaa
3 changed files with 91 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/glib/tmpl/.gitignore vendored
View File

@ -6,3 +6,4 @@ hash_tables.sgml
option.sgml
random_numbers.sgml
threads.sgml
timers.sgml

110
docs/reference/glib/tmpl/timers.sgml
View File

@ -1,110 +0,0 @@
<!-- ##### SECTION Title ##### -->
Timers
<!-- ##### SECTION Short_Description ##### -->
keep track of elapsed time
<!-- ##### SECTION Long_Description ##### -->
<para>
#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.
</para>
<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>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT GTimer ##### -->
<para>
Opaque datatype that records a start time.
</para>
<!-- ##### FUNCTION g_timer_new ##### -->
<para>
Creates a new timer, and starts timing (i.e. g_timer_start() is implicitly
called for you).
</para>
@Returns: a new #GTimer.
<!-- ##### FUNCTION g_timer_start ##### -->
<para>
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.
</para>
@timer: a #GTimer.
<!-- ##### FUNCTION g_timer_stop ##### -->
<para>
Marks an end time, so calls to g_timer_elapsed() will return the difference
between this end time and the start time.
</para>
@timer: a #GTimer.
<!-- ##### FUNCTION g_timer_continue ##### -->
<para>
Resumes a timer that has previously been stopped with g_timer_stop().
g_timer_stop() must be called before using this function.
</para>
@timer: a #GTimer.
@Since: 2.4
<!-- ##### FUNCTION g_timer_elapsed ##### -->
<para>
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>
</para>
@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.
<!-- ##### FUNCTION g_timer_reset ##### -->
<para>
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.
</para>
@timer: a #GTimer.
<!-- ##### FUNCTION g_timer_destroy ##### -->
<para>
Destroys a timer, freeing associated resources.
</para>
@timer: a #GTimer to destroy.

91
glib/gtimer.c
View File

@ -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)