p4.txt

MPICH是MPI的重要研究,提供了一系列的接口函数,为并行计算的实现提供了编程环境.

Some Useful Monitors
====================


In this section we describe some of the specific monitors that are built
into the p4 library. Each of them has its own pre-defined type, which can
be used to allocate storage for them, which should be in shared memory.
See the p4/monitors directory for examples. A lock is itself a monitor,
with no extra delay queues. 


 
 
VOID p4_lock_init(l) 
p4_lock_t *l; 

initializes the lock l. Must be used prior to any attempts to lock or
unlock l. 


 
 
VOID p4_lock(l) 
p4_lock_t *l; 

blocks if the lock l is already locked, otherwise locks l and proceeds. 


 
 
VOID p4_unlock(l) 
p4_lock_t *l; 

unlocks the lock l. 


 
 
VOID p4_getsub(gs,s,max,nprocs) 
p4_getsub_monitor_t *gs; 
int *s,max,nprocs; 

is a procedure used to obtain the next value of a shared counter
(subscript). It takes as its first argument, a pointer to a getsub monitor
that protects the shared counter. It assigns the current value of the counter
to the integer that s points to, and then increments the counter by 1. 
p4_getsub_init initially sets the counter to 0. When the counter
passes the value max, all nprocs processes are returned the value (-1)
once, then the counter is reset to 0 for further use. 


 
 
VOID p4_getsubs(gs,s,max,nprocs,stride) 
p4_getsub_monitor_t *gs; 
int *s,max,nprocs,stride; 

is like p4_getsub except that the counter is increased on each call by 
stride instead of 1. 


 
 
int p4_getsub_init(gs) 
p4_getsub_monitor_t *gs; 

initializes the getsub monitor pointed to by gs; this initialization
includes assigning a value of 0 to the counter that the monitor protects. 

The standard barrier synchronization pattern is expressed as a monitor.
There can be multiple barrier monitors, and one can wait for only some
of the processes at the barrier if this is desired. 


 
 
VOID p4_barrier(b,nprocs) 
p4_barrier_monitor_t *b; 
int nprocs; 

causes the executing process to hang until nprocs processes execute a
barrier instruction with a pointer to the same barrier monitor b as an
argument. 


 
 
int p4_barrier_init(b) 
p4_barrier_monitor_t *b; 

initializes the barrier monitor b; this procedure should be invoked before
you attempt to use the monitor in any operations. 

Finally, the askfor monitor functions like a general dispatcher of work.


 
 
int p4_askfor(af,nprocs,getprob_fxn,problem,reset_fxn) 
p4_askfor_monitor_t *af; 
int nprocs; 
int (*getprob_fxn)(); 
VOID *problem; 
int (*reset_fxn)(); 

requests a new ``problem'' to work on from the problem pool. The
arguments are (1) a pointer to the askfor monitor that protects the
problem pool, (2) the number of processes that call this procedure (with 
af) looking for work, (3) a pointer to the user-written procedure that
obtains a problem from the pool, (4) a pointer that is filled in with the
address of a user-defined representation of a problem to be solved, and
(5) a pointer to a user-written procedure to reset when all problems in the
pool are solved, in case the same monitor is re-used for another set of
problems later. p4_askfor returns an integer indicating whether a
problem was successfully obtained or not: 


 
 
  -1     : program is terminating (some process called p4_progend) 
   0     : a problem was obtained and ``problem'' points to it 
   1     : problem solved by exhaustion, i.e. no more problems to get 
   n > 1 : a process found a solution and called p4_probend with code n 

For a detailed discussion of the ``askfor'' monitor, see [(ref
lusk-overbeek:p4-book)]. 


 
 
int p4_update(af,putprob_fxn,problem) 
p4_askfor_monitor_t *af; 
int (*putprob_fxn)(); 
VOID *problem; 

updates the problem pool being managed by the askfor monitor. The
arguments are (1) a pointer to the askfor monitor that protects the
problem pool, (2) a pointer to the user-written procedure that puts
problems into the pool, and (3) a pointer to a user-defined representation
of a problem to be put in the pool. Putprob_fxn should return 1 if it
did indeed put a new problem into the pool, so that any delayed processes
should wake up and re-examine the pool (this logic is handled by the 
p4_askfor) and 0 if upon entering the monitor and examining its
potential problem together with the data there it decided not to add a new
problem to the pool. It can be assumed that the ``putprob'' logic (defined
by putprob_fxn) is executed inside the monitor. 


 
 
int p4_askfor_init(af) 
p4_askfor_monitor_t *af; 

initializes the askfor monitor af; this procedure should be invoked before
you attempt to use the monitor in any operations. 


 
 
VOID p4_probend(af,code) 
p4_askfor_monitor_t *af; 
int code; 

allows the user process to mark a problem as solved early when several
processes are coordinating their activities via an askfor monitor. The code
is an integer value that will be returned to all processes when they
``askfor'' a new sub-problem to work on. 


 
 
VOID p4_progend(af) 
p4_askfor_monitor_t *af; 

allows a process to cause a return code of (-1) to be returned to all
processes using an askfor monitor. This would typically be called by a
master process to indicate that no more problems are to be solved and that
all slave processes should terminate. 



Functions for Timing p4 Programs
********************************


A small number of simple functions are available for accessing various
clocks and timers. 


 
 
int p4_clock() 

returns a value in milliseconds. This is a wall-clock value, usually
obtained from the system via gettimeofday. Also see p4_ustimer
below. 


 
 
p4_usc_time_t p4_ustimer() 

returns a wall-clock time value in microseconds. The precision of this
number depends on the timer installed on the individual machine. In some
cases the resolution may be no greater than that of p4_clock(). For
arithmetic and printing purposes, the type p4_usc_time_t is an
unsigned long integer. 


 
 
p4_usc_time_t p4_usrollover() 

returns the timer value at which a microsecond timer ``rolls over''. Since 
p4_usc_time_t is a long integer's worth of microseconds, it is likely
that the timer will roll over (become zero) during even medium-length
runs (about 72 minutes on most machines). 



Functions for Debugging p4 Programs
***********************************


P4 has a set of routines to aid in producing a printed trace of events, both
user-defined and pre-defined in the p4 system. 


 
 
VOID p4_dprintf(fmt, va_alist) 
char *fmt; 
va_dcl 

acts just like the standard printf except that the print line is preceded
by a value that identifies the process. This value is typically the string 
pn_u where n represents the p4-assigned id and u represents the unix-id
of the process on its host. However, there are other forms of this value.
For example, the big master is represented as bm_u. Also, if a process
prints before it has a p4-assigned id, then its value will be something like
bm_slave_n_u or rm_slave_n_u. Typically, it is not possible for a
user program to print anything before being assigned an id by p4, but the
p4 system itself may use this procedure to print messages from a
particular process if it encounters problems getting the process
initialized. 


 
 
VOID p4_dprintfl(level, fmt, va_alist) 
int level; 
char *fmt; 
va_dcl 

is like p4_dprintf except that the first argument is an integer
indicating the debugging level that must be in effect before this message
will print. A level of 0 will cause the message to always print. If you run
a program with the debug level set to 5 (via command-line arguments),
then all dprintfl's with level less than or equal to that debug level
will print. See section Command-Line Arguments for how to set the
debug level at run time. 

The debug level can be examined and changed by the user during
execution: 


 
 
int p4_get_dbg_level()      

returns the current debug level for this process and its cluster. 


 
 
VOID p4_set_dbg_level(level)      
int level; 

sets the current debug level for this process and its cluster. P4 itself is
liberally instrumented with p4_dprintfl's of level 10 and above,
leaving levels 0-9 for the user. The greater the debug level of the built-in
messages, the greater understanding of p4 needed by the user to make
sense of them. However, levels as high as 30 may well be useful to the
user trying to debug a p4 program. Roughly speaking, the following
debug levels produce messages about the indicated events. 


 
 
level 10:  created process 
           sent message 
           received message 

level 20:  creating process 
           sending message 
           receiving message 
           process starting 
           process exiting 

level 30:  waiting for ack 
           sending ack 
           sent ack 
           received ack 
           queueing message for later receipt 
           queued message for later receipt 

level 40:  memory management 
           buffer management 

level 50:  reading procgroup 
           other initialization message exchange 

level 60:  send-receive details, especially machine-specific traces 

level 70:  listener interactions: 
            creating listener 
            created listener 
            messages from inside listener 

level 80:  detailed data structures after initialization 

level 90:  detailed tracing of flow thru procedures 

For optimum performance, the test of the debug level required by these
messages can be removed at compile time by not commenting out the 
#define P4_DPRINTFL line in the OPTIONS file (See section 
Introduction). 

The following function is provided to deal with abnormal termination. It
can be called by any process. 


 
 
VOID p4_error(string, value) 
char *string; 
int value; 

prints string as an error message and then forcefully terminates all
co-operating processes and cleans up all shared resources. 


 
 
VOID p4_soft_errors(onoff)      
int onoff; 

enables/disables soft errors, returning the previous setting. The default is
``disabled'', which means that certain p4 functions will call p4_error
instead of returning -1. 

p4_error gets control on certain kinds of interrupts. It is automatically
called for SIGSEGV, SIGBUS, and SIGFPE interrupts, to catch user
programming errors and clean up, after which it returns interrupt
handling to default mode and returns, so that the user may obtain a dump.
It also handles SIGINT interrupts, in which case it cleans up and exits.
Finally, it may be called directly by the user, in which case it cleans up
(other p4 processes and IPC's) and exits. 

Although p4_error is supposed to get rid of all running p4 processes,
it can happen that an error is bad enough that p4 processes are left
running. A primitive aid in finding and killing these processes is the shell
script kj, which takes a string as an argument and then kills processes
containing that string as part of their program names. Currently it only
kills processes on the machine where it is run, but it can be run via rsh
on remote machines. There are other useful scripts (e.g. killipc and 
killp4) in the p4/bin directory to do such things as clean up SYSV IPC
items that may be left when a program abnormally terminates. P4 will
generally cleanup these items if the abnormal termination is a type that
p4 traps, otherwise the user must do the cleanup. This is an unfortunate
side-effect of the way that SYSV handles things, it really should be the
OS's function to take care of this. 

On many machines it is possible to attach a debugger like dbx to a
running process. This is one way to find out where a hanging process is
stuck. 



Miscellaneous Functions
***********************


In this section are found functions that do seem to fit neatly into any of
the other sections. 


 
 
char *p4_version() 

returns a string containing the version number of p4 being run. 


 
 
VOID p4_print_avail_buffs() 

P4 maintains an array of buffer lists of various sizes, so that it can very
rapidly allocate and deallocate buffers. You can see the contents of the
buffer pools at any time by calling this procedure. 


 
 
VOID p4_set_avail_buff(bufidx,size) 
int bufidx; 
int size; 

This procedure is used to set the size of buffers in p4's buffer pools. The
parameter bufidx specifies a particular buffer list, and should be a
number from 0 to 7. The size parameter specifies that buffers up to that
size will be managed by p4 in a particular list. It is important to maintain
the buffer sizes in increasing order. The default list of buffer sizes is 64,
256, 1024, 4096, 16384, 65536, 262144, 1048576. This causes wasted
space if you send only one large message, causing the allocation of a large
buffer which is not reused. Savings in space can be achieved by adjusting
these numbers to correspond with the message sizes of your application.
If no large messages are sent at all, however, no space is wasted since the
large buffers will never be allocated. If you send a message larger that the
largest size in this array, p4 will allocate the buffer, and then free it back
to the system as