Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
AG_TIME(3)		    Library Functions Manual		    AG_TIME(3)

NAME
       AG_Time -- agar time interface

SYNOPSIS
       #include	<agar/core.h>

DESCRIPTION
       These functions provide a low-level interface to	monotonically increas-
       ing  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 differ-
				ent  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	struc-
       ture:

       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.

Agar 1.7		       December	21, 2022		    AG_TIME(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Time&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help