p4.txt

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

 
 
VOID p4_cluster_shmem_sync(cluster_shmem) 
VOID **cluster_shmem; 

This routine is used to synchronize the processes in a cluster before they
begin to use shared memory. 


 
 
VOID p4_get_cluster_masters(numids, ids) 
int *numids, ids[]; 

This procedure fills in the values of numids and ids. It obtains the
p4-id's of all ``cluster masters'' for the program, placing them in the 
ids array and placing the number of id's in numids. 



Functions for Message Passing
*****************************


P4 supports a set of send/receive procedures. These procedures are
``generic'' in the sense that they do not know whether a message must
travel across a network or through shared memory, or via some other
mechanism. They depend on a lower-level set of procedures that handle
local or network (remote) communications. By default, the messages are
assumed to be typed. If the user wishes to use untyped messages, he can
hide the typing by coding some very simple C macros that always use a
single message type. 



Explicit Sending and Receiving of Messages
==========================================


p4_send(type,to,msg,len) 
p4_sendr(type,to,msg,len) 
p4_sendx(type,to,msg,len,datatype) 
p4_sendrx(type,to,msg,len,datatype) 
p4_sendb(type,to,msg,len) 
p4_sendbr(type,to,msg,len) 
p4_sendbx(type,to,msg,len,datatype) 
p4_sendbrx(type,to,msg,len,datatype) 

int type, to, len, datatype; 
char *msg; 

Each of these procedures sends a message. The type argument is an
integer value chosen by the user to represent a message type. The to
argument is an integer value that specifies the p4-id of the process that
should receive the message. The len argument contains the length in
bytes of the message to be passed. Note that some of the procedures have
a ``b'' in their name, e.g. p4_sendb. These procedures assume that the
msg is in a buffer that the user obtained earlier via a p4_msg_alloc;
otherwise, the buffer is assumed to be in the user's local space, and may
cause the message to be copied internally. The procedures with an ``r'' in
the name do not return until an acknowledgement is received from the to
process (the ``r'' stands for rendezvous). Those procedures with an ``x'' in
the name take an extra argument (datatype) that specifies the type of data
in the message; these procedures will use that information to call XDR
for data conversion if the message is being passed to a machine of a
different architecture, i.e. where the internal representation may be
different. The valid values for the datatype parameter are P4INT, 
P4DBL, P4FLT, P4LNG, and P4NOX. The last of these means ``no
translation''. 


 
 
BOOL p4_messages_available(req_type,req_from) 
int *req_type,*req_from; 

returns a BOOL value indicating whether the process has any messages
available or not. The parameters req_type and req_from are both
pointers to integers; they are used as both input and output arguments. On
input, req_type has a value that indicates the type of message that the
user wishes to check for availability (-1 indicates any type). The variable 
req_from is used similarly to indicate who a message is desired from. 


 
 
int p4_recv(req_type,req_from,msg,len_rcvd) 
int *req_type,*req_from,*len_rcvd; 
char **msg; 

takes four arguments. The msg argument is a pointer to a pointer to a 
char. If this value is NULL, then p4 will allocate the buffer for the
message according to its length. That is, one need not know ahead of time
the length of a message being received. If this value is not NULL, then it
points to a p4 message buffer that the user has obtained via 
p4_msg_alloc. The len_rcvd argument is a pointer to an integer
that is assigned the length of the received message. Req_type and 
req_from are both pointers to integers; they are used as both input and
arguments. On input, req_type has a value that indicates the type of
message that the user wishes to receive (-1 indicates any type). It will
block until a message of that type is available. Req_from is used
similarly to indicate who a message is desired from. One important note
about this procedure is that it obtains the area in which to place a
message, and the user must explicitly free that area when finished with it
(see p4_msg_free). There is an option available with p4_recv in
which the user can provide his own buffer rather than having p4 allocate
it. To do this, the user points msg to a buffer that he must obtain via a
call to p4_msg_alloc (see below). No p4_msg_free should be
performed if the same buffer is going to be re-used multiple times. 


 
 
char *p4_msg_alloc(len) 
int len; 


 
 
VOID p4_msg_free(m) 
char *m; 

obtain and free a buffer area that can be used to receive a message. This
procedure should be used for this task because a message has hidden
information which the user is unaware of and therefore should not use 
malloc to obtain the area. 



Global Operations
=================


P4 supports a number of operations for dealing with all processes at once.


 
 
p4_broadcast(type, data, data_len) 
int type; 
char *data; 
int data_len; 


 
 
p4_broadcastx(type, data, data_len, data_type) 
int type; 
char *data; 
int data_len, data_type; 

provide the ability to broadcast messages like p4_send and p4_sendx.
These are semantically equivalent to a loop which uses p4_send or 
p4_sendx to individually send a message to each other process (the
sender is not included.) Messages sent by one of these broadcasts are
received by normal p4_recv's. The implementation of 
p4_broadcast is more efficient than such a loop, since it uses a
``broadcast tree''. One situation to look out for is a normal 
p4_broadcast followed by a p4_send. It is possible for the first
message to arrive at its destination after the second one. The order of
messages in this situation can be enforced with the use of the type
argument. 


 
 
p4_global_op(type,x,nelem,size,op,data_type)  
int type; 
char *x; 
int size, nelem; 
int (*op)(); 
int data_type; 

where op is one of: 

 
 
p4_int_absmax_op() 
p4_int_absmin_op() 
p4_int_max_op() 
p4_int_min_op() 
p4_int_mult_op() 
p4_int_sum_op() 
p4_dbl_absmax_op() 
p4_dbl_absmin_op() 
p4_dbl_max_op() 
p4_dbl_min_op() 
p4_dbl_mult_op() 
p4_dbl_sum_op() 
p4_flt_absmax_op() 
p4_flt_absmin_op() 
p4_flt_max_op() 
p4_flt_min_op() 
p4_flt_mult_op() 
p4_flt_sum_op() 

and data_type is one of P4INT, P4LNG, P4FLT, or P4DBL. 

This collection of routines provide the ability to do a variety of global
operations. See the example program p4/messages/systest.c. They apply
the commutative and associative operation op globally to x on an
element-by-element basis and broadcast the result to all nodes. That is,
each process ends up with 


 
 
   for (i=0; i<n; i++) 
         x[i] = x[node 0][i] op x[node 1][i] op x[node 2][i] op ... 

op should be of the form 


 
 
     VOID op(char *x, char *y, int nelem) 
     { 
         data_type *a = (data_type *) x; 
         data_type *b = (data_type *) y; 

while (nelem--) 
             *a++ operation= *b++; 
     } 

where data_type and operation are chosen appropriately. 

The order in which nodes apply the operation is undefined (hence op
must be commutative and associative). The communication may be
internally sub-blocked so the function op should not be hardwired to
specific vector lengths. 

This is still a relatively primitive version, which gathers the necessary
data up a balanced binary tree and then uses p4_broadcast to send the
results back. The type argument specifies the message type to be used in
the communication associated with this global operation. 

Strictly speaking, the size parameter, which is size in bytes of one
element, is unnecessary. It is retained for backward compatibility. 


 
 
VOID p4_global_barrier(type) 
int type; 

This procedure takes one argument which is the message type to be used
for internal message-passing. It causes the invoking process to hang until
all processes specified in the procgroup file have invoked the procedure. 



Functions for Shared Memory
***************************


Here is a simple example of a shared-memory program using monitors.
In this program, each process retrieves values from a shared loop index. A
monitor is used to ensure that all values are retrieved exactly once. 


 
 
#include "p4.h" 

struct globmem { 
    p4_getsub_monitor_t getsub; 
} *glob; 

main(argc,argv) 
int  argc; 
char **argv; 
{ 
    p4_initenv(&argc,argv); 

glob = (struct globmem *) p4_shmalloc(sizeof(struct globmem)); 
    p4_getsub_init(&(glob->getsub)); 

p4_create_procgroup(); 
    worker(); 
    p4_wait_for_end(); 
} 

worker() 
{ 
    int i, nprocs; 

nprocs = p4_num_total_ids(); 
    i = 0; 
    while (i >= 0) 
    { 
        p4_getsub(&(glob->getsub),&i,10,nprocs); 
        p4_dprintf("I got %d\n",i); 
    } 
} 




Managing Shared and Local Memory
================================


The following functions are just basic memory management routines. 


 
 
char *p4_malloc(n) 
int n; 

typically acts like the standard malloc, but may be rewritten for user
systems that require different operation. 


 
 
VOID p4_free(p) 
char *p; 

typically acts like the standard free, but may be rewritten for user
systems that require different operation. 


 
 
char *p4_shmalloc(n) 
int n; 

acts like the standard malloc except will obtain shared memory on
machines that support sharing memory among processes. Compare with 
p4_malloc. 


 
 
VOID p4_shfree(p) 
char *p; 

frees memory obtained with p4_shmalloc. Compare with p4_free. 



Shared Memory Data Types
========================


The abstraction provided by p4 for managing data in shared memory is 
monitors. Good places to learn about the monitor concept in general are
[(ref pbh:architecture)] and [(ref hoare:monitors)]. The specific approach
taken by p4 is described in [(ref lusk-overbeek:p4-book)]. P4 provides
several useful monitors (p4_barrier_t, p4_getsub_monitor_t,
p4_askfor_monitor_t) as well as a general monitor type to help
the user in constructing his own monitors (p4_monitor_t). 



Monitor-Building Primitives
===========================


The following functions can be used to construct monitors. A monitor so
constructed has the type p4_monitor_t. 


 
 
int p4_moninit(m,i) 
p4_monitor_t *m; 
int i; 

initializes the monitor pointed to by m and gives it i queues for processes
to wait on while they are blocked (see p4_mdelay). One queue is
sufficient for most purposes. The queues are numbered beginning with 0. 


 
 
VOID p4_menter(m) 
p4_monitor_t *m; 

enter the monitor pointed to by m. By the definition of a monitor, access
is restricted to a single process in the monitor at a time (if everybody
plays by the rules). 


 
 
VOID p4_mexit(m) 
p4_monitor_t *m; 

exits the monitor pointed to by m. You are of course assumed to have
previously entered that monitor. 


 
 
VOID p4_mcontinue(m,i) 
p4_monitor_t *m; 
int i; 

checks to see if there are any processes blocked on the i-th queue of the
monitor m and causes one of them to be released for entry to the monitor
if so. If there are no such processes, the invoking process simply exits.
Note that a process could have been blocked previously by invoking the
procedure p4_mdelay. The queues are numbered beginning with 0. 


 
 
VOID p4_mdelay(m,i) 
p4_monitor_t *m; 
int i; 

permits a process to delay itself on the i-th queue of monitor m if the
process wishes to release the monitor, but wants to be waked up by
another process later (via the procedure p4_mcontinue). The queues
are numbered beginning with 0.