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

h
hg(3) hg(3)
(Mercury Library)
hg_public_is_reporting()
will return zero if not reporting and non-zero if reporting
hg_public_is_running()
will return zero if not running and non-zero if running.
hg_public_is_onRunQ()
will return 0 if not on run queue and non-zero if on run queue.
hg_public_nMailboxes()
returns the total number of mailboxes available for attachment.
hg_public_nMailboxesInUse()
returns the number of mailboxes available for attachment at the
time of calling.
hg_gethrcycles()
returns the number of machine cycles since the machine was booted.
hg_gethrtime()
returns the number of nanoseconds since the machine was booted.
hg_nano_to_cycle_ratio()
returns the number of nanoseconds/machine cycle for that processor in
specific.
hg_busywait()
returns 0 on successful completion.
hg_getspu() returns the number of the processor the thread is running on.
hg_context_switch_tries()
returns the total number of times the kernel thread has switched out
(or at least attempted to switch out).
hg_context_switch_involuntary()
returns the number of times the kernel thread has involun-
tarily switched out.
hg_context_switch_voluntary()
returns the number of times the kernel thread has voluntarily
switched out.
hg_setcrit() returns the number of times the thread has yielded the processor.
ERRORS
The only error returned by the libhg APIs is HG_ERROR. This will be returned if any of the following
calls fail:
hg_public_init()
, hg_public_nMailboxes(), hg_public_nMailboxesInUse()
, and
hg_busywait().
EXAMPLES
Below is a scenario on how an application may use Mercury APIs achieve performance.
Since threads may remove mailboxes at any point of time,
hg_public_is_reporting()
can help us
find that. If the mailbox is still in use, the run state of the thread associated with it can be obtained. This
can be important at times because if a thread has detached the mailbox, but since the mailbox still remains
mapped, the probing thread may obtain incorrect information about the thread being probed. Another
situation could be that even if the mailbox is in use, it may have been given up by the previous thread and
reassigned to a completely new thread.
The kernel is less likely to preempt a thread when it’s running in a critical region than when it’s not.
Therefore, code regions where locks are held are good places to mark as critical since application
throughput can drop dramatically if a thread holding critical resources stops running while other threads
are waiting to acquire those resources.
Since
hg_setcrit() does not enter the kernel, it is very fast and does not significantly increase the
length of critical paths. If setting willing_to_block to 1 (instead of 0), hg_setcrit() will yield the pro-
cessor, if necessary, prior to beginning the critical region to reduce the likelihood of being preempted within
the critical region.
Here is one recommended sequence:
hg_setcrit( lock_address, WILLING_TO_BLOCK);
acquire lock
critical region
release lock
hg_setcrit(CRIT_OFF, UNWILLING_TO_BLOCK);
Alternately,
hg_setcrit( lock_address, UNWILLING_TO_BLOCK);
acquire lock
critical region
648 Hewlett-Packard Company − 4 − HP-UX 11i Version 3: February 2007