## Timers

Timers — keep track of elapsed time

## Synopsis

    #include <glib.h>

                        GTimer;
    GTimer*             g_timer_new                         (void);
    void                g_timer_start                       (GTimer *timer);
    void                g_timer_stop                        (GTimer *timer);
    void                g_timer_continue                    (GTimer *timer);
    gdouble             g_timer_elapsed                     (GTimer *timer,
                                                             gulong *microseconds);
    void                g_timer_reset                       (GTimer *timer);
    void                g_timer_destroy                     (GTimer *timer);

## Description

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

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.

## Details

### GTimer

    typedef struct _GTimer GTimer;

Opaque datatype that records a start time.

### g_timer_new ()

    GTimer*             g_timer_new                         (void);

Creates a new timer, and starts timing (i.e. `g_timer_start()` is implicitly called for you).

Returns : | a new GTimer.

### g_timer_start ()

    void                g_timer_start                       (GTimer *timer);

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.

### g_timer_stop ()

    void                g_timer_stop                        (GTimer *timer);

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.

### g_timer_continue ()

    void                g_timer_continue                    (GTimer *timer);

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

### g_timer_elapsed ()

    gdouble             g_timer_elapsed                     (GTimer *timer,
                                                             gulong *microseconds);

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

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.

### g_timer_reset ()

    void                g_timer_reset                       (GTimer *timer);

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.

### g_timer_destroy ()

    void                g_timer_destroy                     (GTimer *timer);

Destroys a timer, freeing associated resources.

`timer` : | a GTimer to destroy.