AG_TIME(3)

NAME
AG_Time - agar time interface

SYNOPSIS

    #include <agar/core.h>

DESCRIPTION
These functions provide a low-level interface to monotonically increasing time sources. Different time backends may be implemented (see INTERNAL API below). Agar provides the following backends:

agTimeOps_dummy
    No-op (timers will be unavailable).

agTimeOps_gettimeofday
    BSD-style gettimeofday() interface.

agTimeOps_posix
    The POSIX clock_gettime() interface.

agTimeOps_renderer
    Monotonic clock which stops while graphical rendering is performed. This is useful for applications performing offline rendering, where the render may be influenced by different threads relying on Agar timers or AG_Delay() calls. It requires the POSIX clock_gettime() interface.

agTimeOps_win32
    The MS Windows winmm API.

INTERFACE
Uint32 AG_GetTicks(void)

void AG_Delay(Uint32 t)

void AG_SetTimeOps(const AG_TimeOps *ops)

The AG_GetTicks() function returns the current time in ticks. One tick usually corresponds to one millisecond.

The AG_Delay() function blocks the current thread, waiting at least t ticks before returning. The exact amount of time which AG_Delay() waits is platform and backend dependent.

The AG_SetTimeOps() function selects a time backend (see below).

BACKEND INTERFACE
The argument to AG_SetTimeOps() should point to the following structure:

    typedef struct ag_time_ops {
    	const char *name;
    	void   (*Init)(void);
    	void   (*Destroy)(void);
    	Uint32 (*GetTicks)(void);
    	void   (*Delay)(Uint32);
    } AG_TimeOps;

Init() performs any necessary initialization. Destroy() cleans up any allocated resources.

The GetTicks() operation is the backend to AG_GetTicks() and Delay() is the backend to AG_Delay().

EXAMPLES
The following code uses AG_GetTicks() to estimate the running time of a routine:

    Uint32 t1, t2;
    t1 = AG_GetTicks();
    MyFunc();
    t2 = AG_GetTicks();
    AG_Verbose("MyFunc() ran for %u ticks\n",
        t2 - t1);

The following code selects the rendering-aware time backend agTimeOps_renderer if it's available:

    #include <agar/config/have_clock_gettime.h>
    #include <agar/config/have_pthreads.h>
    #if defined(HAVE_CLOCK_GETTIME) && \
        defined(HAVE_PTHREADS)
    AG_SetTimeOps(&agTimeOps_renderer);
    #endif

SEE ALSO
AG_Intro(3), AG_Timer(3)

HISTORY
The AG_Time interface first appeared in Agar 1.3.4.