hg.3 (2010 09)

h
hg(3) hg(3)
(Mercury Library)
hg_gethrtime (void);
hg_gethrtime()
is identical to hg_gethrcycles()
but returns the time since boot in
nanoseconds instead of machine cycles.
This call can generally be expected to return times in a monotonically-increasing sequence too, but
there is an exception. The exact clock rate each processor runs at can drift back and forth by a
small amount around the central, rated value. If two threads conspire to trade time values back
and forth through a very high speed conduit (like shared memory) this drift can be observed as
timestamps occurring out of sequence. Order inversions of a few hundred cycles happen occasion-
ally. The high speed exchange and a high speed time interface are required, however. A slower
interface like
gethrtime() is less capable of observing this clock jitter.
gettimeofday()
exhi-
bits no such problems at all because the calling processor always sychronizes the request with pro-
cessor zero. This is one of the reasons
gettimeofday() is so much slower than
gethrtime()
and hg_gethrcycles()
.
Nevertheless, threads sticking to more mundane uses of the time, such as measuring intervals and
generating (more widely spaced) timestamps, should have no difficulty.
hg_nano_to_cycle_ratio (void);
hg_nano_to_cycle_ratio()
returns the number of nanoseconds/machine cycle for that pro-
cessor in specific.
hg_busywait (double seconds);
hg_busywait() spins in user mode until the requested number of seconds has elapsed. The
actual elapsed time will be equal to or greater than the seconds specified.
hg_getspu (void);
hg_getspu() returns the number of the spu the thread is running on. Remember that the thread
can conceivably switch to another processor between the time of the call and when the information
is used.
hg_context_switch_tries (void);
hg_context_switch_tries()
returns the total number of times the kernel thread has
switched out (or at least attempted to switch out). This includes both voluntary and involuntary
switch-outs.
hg_context_switch_involuntary (void);
hg_context_switch_involuntary()
returns the number of times the kernel thread has
involuntarily switched out (that is, the number of times it has been preempted by another thread).
hg_context_switch_voluntary (void);
hg_context_switch_voluntary()
returns the number of times the kernel thread has volun-
tarily switched out (such as taking a page fault ). The number of voluntary switch-outs is given by
the difference between total switch-outs and involuntary switch-outs.
hg_setcrit (unsigned long on_or_off, int willing_to_block);
hg_setcrit() informs the kernel when the thread is entering or leaving a critical region of code.
on_or_off should be non-zero when entering a critical region and 0 when leaving.
Although any non-zero value will work for on_or_off, passing in the lock address or some other key
piece of information such as the address of the calling routine, may be useful.
The kernel uses this information to help schedule the thread - when possible, the kernel will avoid
switching the thread to a non-runnable state when this critical region state is set. However, threads
that spend too much time in regions marked critical will eventually be switched out because the ker-
nel must fairly balance the needs of different threads on the system.
The willing_to_block parameter indicates that the thread is willing to block if necessary to set up
this critical region. Threads that are willing to block before entry to a critical region are less likely
to be involuntarily blocked in the critical region. A guideline is to set willing_to_block to 1 (or some
other non-zero value) upon entry to the outermost critical region and to set it to zero in the inner
ones.
hg_setcrit() does not have any notion of nesting, so the decision about calling hg_setcrit()
in nested critical regions is the responsibility of the calling thread.
RETURN VALUES
hg_public_init() returns the address of the mailbox if the call is successful, NULL otherwise.
HP-UX 11i Version 3: September 2010 − 3 − Hewlett-Packard Company 3