hg.3 (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

hg(3) hg(3)

(Mercury Library)

NAME

hg: hg_busywait(), hg_context_switch_involuntary(), hg_context_switch_tries(),

hg_context_switch_voluntary(), hg_gethrcycles(), hg_gethrtime(), hg_getspu(), hg_nano_to_cycle_ratio(),

hg_public_init(), hg_public_is_onRunQ(), hg_public_is_reporting(), hg_public_is_running(),

hg_public_nMailboxes(), hg_public_nMailboxesInUse(), hg_public_remove(), hg_setcrit() - Mercury

Library Interfaces to transfer data between user and kernel space in a lightweight manner

SYNOPSIS

#include<sys/mercury.h>

cc ﬂags ﬁlename -lhg

Mercury Public Interfaces

uint64_t hg_public_init(void);

uint64_t hg_public_remove(void);

uint64_t hg_public_is_reporting(uint64_t hg_public_handle);

uint64_t hg_public_is_running(uint64_t hg_public_handle);

uint64_t hg_public_is_onRunQ(uint64_t hg_public_handle);

uint64_t hg_public_nMailboxes(void);

uint64_t hg_public_nMailboxesInUse(void);

Mercury Private Interfaces

uint64_t hg_gethrcycles(void);

uint64_t hg_gethrtime(void);

double hg_nano_to_cycle_ratio(void);

uint64_t hg_busywait(double seconds);

spu_t hg_getspu(void);

uint64_t hg_context_switch_tries(void);

uint64_t hg_context_switch_involuntary(void);

uint64_t hg_context_switch_voluntary(void);

uint64_t hg_setcrit(unsigned long on_or_off, int willing_to_block);

DESCRIPTION

The Mercury Library Interface (HG) provides a high performance interface between user programs

and the kernel, making it possible to transfer key pieces of information back and forth at high speed.

Communication between the user space and kernel is relatively slow due to the overhead of making a sys-

tem call. The Mercury APIs help by avoiding most or all of this overhead.

The information exchanged can be divided into two broad categories:

• Public data:

Information about speciﬁc kernel threads likely to be of interest to other threads. This is provided by

the Mercury Public Interface functions. This information received is the present run state of the

threads being queried.

• Private data:

Information likely to be of interest to the same thread alone. The Mercury Private Interfaces allow

the kernel to keep a thread informed of a number of events usually of use or interest only to that

thread.

A thread needs to register before any other thread can view its public information. There is no need to

If a thread does register itself, it is provided a handle, which may be communicated to other threads.

Mercury Library provides APIs that query the handle for the underlying thread’s run state. Hence the

thread is recognized by the handle assigned to it.

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1

Summary of content (6 pages)

PAGE 1
hg(3) hg(3) (Mercury Library) NAME hg: hg_busywait(), hg_context_switch_involuntary(), hg_context_switch_tries(), hg_context_switch_voluntary(), hg_gethrcycles(), hg_gethrtime(), hg_getspu(), hg_nano_to_cycle_ratio(), hg_public_init(), hg_public_is_onRunQ(), hg_public_is_reporting(), hg_public_is_running(), hg_public_nMailboxes(), hg_public_nMailboxesInUse(), hg_public_remove(), hg_setcrit() - Mercury Library Interfaces to transfer data between user and kernel space in a lightweight manner SYNOPSIS #incl
PAGE 2
hg(3) hg(3) (Mercury Library) The run state information of any thread is stored in a publicly available user-mapped mailbox . The kernel continually posts and updates the run state of the calling kernel thread in the mailbox , when possible. 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.
PAGE 3
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.
PAGE 4
hg(3) hg(3) (Mercury Library) hg_public_remove() returns the value 1, in case of success. 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.
PAGE 5
hg(3) hg(3) (Mercury Library) critical region release lock hg_setcrit(CRIT_OFF, WILLING_TO_BLOCK); Or ... hg_setcrit(lock_address , WILLING_TO_BLOCK); acquire lock critical region release lock hg_setcrit(CRIT_OFF, WILLING_TO_BLOCK); It is never absolutely necessary to set WILLING_TO_BLOCK, but it reduces your chances of being switched out during the critical region. Remember that WILLING_TO_BLOCK means that you are willing to block during the hg_setcrit() call, not during the critical region.
PAGE 6
(Notes) A (Notes) hA 6 Hewlett-Packard Company −1− HP-UX 11i Version 3: September 2010