HP-UX Reference (11i v3 07/02) - 3 Library Functions A-M (vol 6)

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 occasionally. 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() exhibits no such
problems at all because the calling processor always sychronizes the request with processor 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 proces-
sor 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.
hg_public_remove() returns the value 1, in case of success.
HP-UX 11i Version 3: February 2007 − 3 − Hewlett-Packard Company 647