hg.3 (2010 09)
h
hg(3) hg(3)
(Mercury Library)
The run state information of any thread is stored in a publicly available user-mapped mailbox . The ker-
nel continually posts and updates the run state of the calling kernel thread in the mailbox, when possi-
ble. Keep in mind that all information is to be regarded as hints about the state and that no guarantees
are implied, from any of the APIs providing the run state information on threads, although a good faith
effort is made to keep it accurate.
If you are using MxN threads, the use of the Mercury library public interface is not recommended. This
is because the state shown by the interface is always that of the underlying kernel thread. Therefore a
thread of scope
PTHREAD_FORCE_SCOPE_PROCESS
, which moves from kernel thread to kernel thread,
would have confusing information reported about it. Always use
PTHREAD_FORCE_SCOPE_SYSTEM
for
all threads if you are using the Mercury public interface. The default scope of threads on systems which
can use Mercury is
PTHREAD_FORCE_SCOPE_SYSTEM
. So one can use Mercury on such systems
without having to change the scope. For more information, see pthread_attr_setscope(3T).
A context switch is the act of a thread ceasing to run on a cpu for some reason and then later starting to
run again; this pair of actions is one context switch ("switching out" then "switching in"). A "voluntary"
context switch is one that is caused by something the thread does that requires it to stop running. For
example, a thread calling
sched_yield()
or a thread blocking for a page fault. An "involuntary" con-
text switch is one that is imposed on the thread by the operating system for policy reasons. For example,
the operating system switching a thread out to run a higher priority thread.
libhg Public Interfaces
These are the public interface provided by
libhg:
hg_public_init(void);
hg_public_init() allocates and initializes the mailbox , where the kernel can update the run
state of the calling kernel thread. Updating begins immediately. The mailbox is mapped into the
address space of every thread in the system so any thread that’s been given the address of this mail-
box will be able to check at any time to see if the thread is running or not.
hg_public_remove(void);
hg_public_remove()
terminates the updating of run state information and deallocates the
mailbox . Removed mailboxes remain mapped, so user programs that continue to examine them will
not fault, but the contents will be marked
HG_PUBLIC_INVALID
(until the kernel reuses the mail-
box). A well-written application will keep its threads informed when it removes a mailbox .
hg_public_is_running(uint64_t hg_public_handle);
hg_public_is_running()
checks the provided mailbox and returns a boolean indicator of
whether the thread is running or not. A thread may be not running because it has switched out,
because it has terminated, or because it has removed itself using
hg_public_remove()
.
hg_public_is_reporting (uint64_t hg_public_handle);
hg_public_is_reporting()
checks the provided mailbox and returns a boolean indicator of
whether a thread is reporting to the mailbox or not.
hg_public_is_onRunQ (uint64_t hg_public_handle);
hg_public_is_onRunQ() checks the provided mailbox and returns a boolean indicator of
whether a thread is currently ready to run, but not yet running.
hg_public_nMailboxes (void);
hg_public_nMailboxes() returns the maximum number of attachments the kernel supports.
hg_public_nMailboxesInUse (void);
hg_public_nMailboxesInUse() returns the current number of attachments in service
system-wide.
libhg Priviate Interfaces
These are the private interface provided by
libhg:
hg_gethrcycles (void);
hg_gethrcycles() returns the number of machine cycles since the system was booted. This
time is unaffected by settimeofday() and adjtime() calls (and their like) and can be used
without regard for which processor it is called from.
This call will always return times in a monotonically increasing sequence when called on the same
processor or when called by the same thread, even when that thread moves from processor to pro-
cessor. Under some circumstances, discussed in more detail in
hg_gethrtime(), communicating
threads may occasionally find their times slightly out of sequence.
2 Hewlett-Packard Company − 2 − HP-UX 11i Version 3: September 2010