pfTime(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfTime(3pf)NAME
pfInitClock, pfGetTime, pfClockMode, pfGetClockMode, pfClockName,
pfGetClockName, pfWrapClock - Initialize and query high resolution clock
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pid_t pfInitClock(double time);
double pfGetTime(void);
void pfClockMode(int mode);
int pfGetClockMode(void);
void pfClockName(char *name);
const char * pfGetClockName(char *name);
void pfWrapClock(void);
DESCRIPTION
Most SGI platforms have high resolution hardware timers. The routines
described in this man page provide a simple interface to these timers.
On the first call to pfInitClock, OpenGL Performer finds the highest
resolution clock available and initializes it, setting the initial time
to time seconds. Subsequent calls simply reset the initial time.
pfGetTime returns a high resolution clock time in seconds that is
relative to the initial time set by pfInitClock. It determines the
highest resolution clock available and uses that clock in all subsequent
calls. On Indy, Indigo, Indigo2, 4D/35, Power Series systems with IO3
boards, and Onyx, the resolution of the clock is submicrosecond. If the
hardware does not support a high resolution counter, the time of day
clock is used which typically has 10ms resolution (see below).
By default, processes forked after the first call to pfInitClock share
the same clock. All such related processes receive the same time from
pfGetTime and see the effects of any subsequent calls to pfInitClock.
Unrelated processes can similarly share a single clock by invoking
pfClockName before the first call to pfInitClock. pfClockName allows a
character string name to be associated with a clock before it is
initialized. pfClockName has no effect after the clock has been
initialized. pfGetClockName returns the name of the clock.
OpenGL Performer periodically checks to see if the underlying hardware
counter has wrapped by having an interval timer (see setitimer(2))
regularly invoke pfWrapClock. By default, this interval timer and the
associated alarm signal are handled in a separate process created by
pfInitClock. The wrapping behavior can be changed by calling pfClockMode
Page 1
pfTime(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfTime(3pf)
before the first call to pfInitClock. A mode of PFCLOCK_APPWRAP causes
wrapping to be handled in the process that called pfInitClock. In this
case, the SIGALRM signals generated by the interval timer are generated
and handled in that process. Wrap checking can be disabled altogether
with a mode of PFCLOCK_NOWRAP. In this case, the application should
invoke pfWrapClock with sufficient frequency to avoid missing a cycle of
the counter (typically the hardware counters wrap every 60-120 secs, but
the R3000 Indigo's clock wraps every 500ms). pfGetClockMode returns the
clock mode.
When wrapping is done in a separate process, only one process is spawned,
regardless of the number of processes using the same clock. If the
calling process has super-user privileges, both the spawned process and
the kernel clock functions are forced to run on CPU 0. pfInitClock
returns the process ID of the process handling clock wrapping and 0
otherwise. A value of -1 indicates failure.
NOTES
If none of the hardware clocks are available, the time of day clock is
used, but with only 10ms resolution it is insufficient for many
applications such as frame rate control. In this case, it may be useful
to enable the fast clock (see ftimer(1)).
The pfDataPool file for clock data is created in the directory /usr/tmp
or in the directory indicated by the PFTMPDIR environment variable, if it
is specified.
Processes specifying a clock of the same name, share that clock through a
pfDataPool. With an unnamed clock, the pfDataPool is deleted on exit,
but when using a named clock, the application must explicitly call
pfDataPool::release with the clock name to remove the pfDataPool.
SEE ALSO
fork, ftimer, setitimer, lboot
Page 2
