p4.txt

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

        int myid, size, nprocs, from, i, type; 

myid = p4_get_my_id(); 
        nprocs = p4_num_total_ids(); 
        for (i=0; i < nprocs; i++) 
        { 
            if (i != myid) 
                p4_send(100, i, msg, strlen(msg)+1); 
        } 
        for (i=0; i < nprocs - 1; i++) 
        { 
            type = -1; 
            from = -1; 
            incoming = NULL; 
            p4_recv(&type,&from,&incoming,&size); 
            printf("%d received msg=:%s: from %d",myid,incoming,from); 
            p4_msg_free(incoming); 
        } 
    } 

This program demonstrates several features of p4's support for
message-passing. Before we get into the specifics however, let's examine
the overall logic of the program. Each process determines its own id and
the total number of processes executing in this run (including process 0).
Then, in the first for-loop, each process sends a single message to each of
the other processes. Finally, in the second for-loop, each process receives
a message from each of the other processes. 

The p4_send call requires 4 arguments: 

 o a message type (arbitrarily chosen to be 100 here) 
 o the id of the process to receive the message 
 o the message itself 
 o the size of the message 


The use of p4_recv is slightly more complicated. First, we assign -1 to
each of the parameters type and from. This is done because -1
represents a wildcard value indicating we are willing to receive a message
of any type from any process. Here, we could have coded type to be 100,
and specified from equal to the value of i each time through the loop
(skipping our own id). By setting incoming to NULL, we have also
indicated to p4_recv that we do not have a buffer in which to place the
received message, so p4_recv should obtain a buffer for us and place
the message in that buffer. p4_recv treats these three parameters as
both input and output values. Thus, it alters the value of each such that 
type and from indicate the type of message received and the id of the
process that sent it. The value of incoming is altered to point to the
buffer where the message was placed. The size parameter is strictly an
output parameter and indicates the size of the received message. It is
possible for the user to provide his own buffer; this will be demonstrated
later. 

Finally, note that p4_msg_free frees the message buffer obtained by 
p4_recv. The procedure p4_msg_free should be called only after
the contents of the message are no longer needed. P4_msg_free should
be used to free these buffers because, although a user only sees the data
portion of a message, p4 internally represents a message as a structured
data item. 

To compile and link this program for execution, you need to create a
makefile. We will assume that you have installed p4 in /usr/local/p4 and
that you have typed the program above into a file name p4simple.c in the
directory /home/mylogin/p4pgms. 

To build your makefile, copy the file 

 
 
    /usr/local/p4/messages/makefile.proto 

into your working directory. This is a prototype makefile that contains
machine-independent information, and which p4 can use to build a
machine-specific makefile for your program. This prototype makefile
contains information about several sample programs that demonstrate
message-passing in p4. If you edit this file, you will see information for
making a program named sr_test. Do a global change of sr_test to
p4simple. You should also change the value of P4_HOME_DIR. It
should contain the full pathname of the p4 system, e.g. /usr/local/p4. Now
change directories to /usr/local/p4 and type: 


 
 
make makefiles P4ARCH=<machine_type> DIRS=/home/mylogin/p4pgms 

where <machine_type> is the machine type that you specified when
you installed p4 on your machine. Now, you should be able to change
back to your directory and see a file named Makefile there. You should
then be able to type: 


 
 
    make p4simple 

There is one last piece missing before you can execute your program.
Recall that p4_create_procgroup needs to know how many
processes to start and where to start them; it reads a file (called a 
procgroup file) to gather this information. P4 always assumes that you
have a master process, and that you describe the slave processes (process
groups) in the procgroup file. You can name a procgroup file any name
you choose, but <progname>.pg is the default name. For example, in
this case your procgroup file should be named p4simple.pg. The
information contained in procgroup files can get fairly involved, but if
you have a computer that supports shared memory among processes, then
you can code a very simple example at first. 

Let us suppose first that you want to run your program on a network of
workstations. Then your procgroup should look something like: 


 
 
    local O 
    some.network.machine 1 /home/me/p4progs/p4simple 

This file indicates that you wish to run only the master on the local
machine (the one you are logged into when you execute the program) and
one slave on the machine some.network.machine. 

Now, all you have to do to run your program is type: 


 
 
    p4simple 

You should see a line printed each time a process receives a message from
another process (on some machines, there may be a restriction that only
one process can do I/O, however such restrictions are not common).
Experiment by changing the number of slaves indicated in the procgroup
file. 

You may notice that even a small p4 program becomes large when linked
with the p4 library. You might consider using strip to reduce the size
or removing -g from the CFLAGS in the makefile. 



Command-Line Arguments
**********************


The command-line arguments to a p4 program are all optional. 

 
 
  -p4help            get this information, then exit 
  -p4pg      <file>  set procgroup file 
  -p4dbg    <level>  set debug level 
  -p4rdbg   <level>  set remote debug level 
  -p4gm      <size>  set global memory size 
  -p4dmn   <domain>  provide local domain name 
  -p4out     <file>  set output file for master 
  -p4rout    <file>  set output file prefix for remote masters 
  -p4ssport <port#>  set private port number for secure server 
  -p4norem           don't start remote processes 
  -p4log             enable internal p4 logging by alog 
  -p4version         print current p4 version number 

In version 1.4, these flag names are valid without their p4 prefix, for
backward compatibility. 

If one specifies -p4norem on the command line, p4 will not actually
start the processes. The master process prints a message suggesting how
the user can do it. The point of this option is to enable the user to start the
remote processes under his favorite debugger, for instance. The option
only makes sense when processes are being started remotely, such as on a
workstation network. 



The p4 Function Library
***********************


Overview of the Library
=======================


In the following sections, we provide details for each p4 function in the
library. The procedures are gathered into the following groups: 

 o Functions for managing processes and clusters 
 o Functions for message passing 
 o Functions for shared memory 
 o Functions for timing p4 programs 
 o Functions for debugging p4 programs 
 o Miscellaneous functions 
 o Fortran interface functions 




Return Codes from p4 Functions
==============================


Most p4 functions return -1 if an error occurs. Some, however, call the
function p4_error when severe errors occur. This function prints a
message and then attempts to terminate all of the user's processes See
section Functions for Debugging p4 Programs. 



p4 Functions for Managing Processes and
***************************************
Clusters
********


In some situations a p4 procedure will give an error message and then
exit. This is typically done as a result of a failed system call and handled
by calling the p4 procedure named p4_error that examines the return
values from socket procedures, etc. Most of the time however, the
procedures simply return a value. Some of the procedures return no value
and thus are declared to return VOID. Some of the procedures return
either a pointer to a character string or NULL; NULL indicates an error.
The remaining procedures return an integer value; (-1) indicates an error. 



Functions for Process Management
================================


In this section we describe the p4 functions needed for basic creation and
termination of processes. 


 
 
int p4_initenv(argc,argv) 
int *argc; 
char **argv; 

should be called by your program before an attempt is made to use any p4
procedures or data areas. We suggest making it the first executable
statement in your program. p4_initenv parses the command line
arguments and extracts the ones intended for p4 ignoring all others (see
the discussion of command line arguments). Note that you pass the
address of argc to p4_initenv so that it can actually remove its own
arguments before your program looks at them. 


 
 
int p4_create(fxn) 
int (*fxn)(); 

 
int p4_create_procgroup() 

There are two procedures that you can use to create processes in p4, 
p4_create_procgroup and p4_create. Processes created via 
p4_create are said to be ``user-managed'' whereas those created by 
p4_create_procgroup are ``p4-managed''. The p4-managed
processes are automatically assigned unique id's (beginning with 0 for the
big master), they have message queues allocated for them so that they can
do message-passing, and they are able to run either on a shared-memory
multiprocessor with the creating process or they can run on a separate
machine. Processes created via p4_create do not have any of these
advantages. They must develop their own id's, they cannot do
message-passing, and they can only run on a shared-memory
multiprocessor with the creating process. The only disadvantage of 
p4_create_procgroup is that you must build a procgroup file
describing the set of required slave processes before the master program
begins execution. This eliminates the possibility of determining late in
the execution exactly how many processes you want to use to solve a
problem. Generally, this is not a problem, especially since we can
combine p4_create_procgroup and p4_create in the following
way: You can use p4_create_procgroup to develop a network of
processes that talk to each other via messages. Each of those processes can
create further processes to help it out as necessary. The original set of
processes communicate with their local slaves through shared data areas
and with each other via message-passing. 

p4_create receives one argument that is a pointer to a function. It
creates a single new process that executes the indicated function. The new
process may share data areas (in shared memory) with the parent process.
However, the new process is not managed by the p4 system in the sense
that it is not assigned an id, it cannot pass messages, etc. The only p4
procedure that deals with user-managed slaves is p4_create. No other
procedures are even aware of their existence. 

p4_create_procgroup reads your procgroup file to determine the
number of slave processes to create and where they are to be placed. It
looks first for the file specified on the command line following the 
-p4pg argument if there is one. If there is no such argument, it looks for
a file with the same name as the executable (master) file, with the .pg
suffix. If it does not find one, it looks for a file named procgroup. It
builds a procgroup table that describes all created processes and gives a
copy of the table to each process. The processes then use the table to
discover how to communicate with each other (processes in a cluster can
send messages directly through shared memory or some other
vendor-specific mechanism), others communicate via sockets). An
alternative method is to build the table in memory yourself and use 
p4_startup. 

The effect of p4_create_procgroup can be obtained in another
way if a system would prefer to use its own way of specifying the
locations of processes. A user may allocate the procgroup data structure
and then fill it in ``by hand'' rather than by reading a file in p4 procgroup
format. The following procedures support this method of starting
processes. 


 
 
struct p4_procgroup *p4_alloc_procgroup() 

allocates a procgroup data structure of the form described in p4.h. The
formats of individual entries (p4_procgroup_entry) are given there
as well. 


 
 
int p4_startup(pg) 
struct p4_procgroup *pg; 

starts processes as specified by an an already-created procgroup data
structure allocated by p4_alloc_procgroup and filled in by the user
using the structures p4_procgroup_entry and p4_procgroup. 


 
 
VOID p4_wait_for_end() 

is the p4 termination/cleanup procedure that you should invoke at the end
of every execution of a program that uses p4. For the master process, it
does some termination processing and then waits for slave processes to
end. It should be called by all processes. 


 
 
int p4_get_my_id() 

returns an integer value representing the id of the process assigned by the
p4 system. If the process is not a p4-managed process, the value (-1) is
returned. 


 
 
int p4_num_total_ids() 

returns an integer value indicating the total number of ids started by p4 in
all clusters, including the big master and all remote masters. 


 
 
int p4_num_total_slaves() 

returns an integer value indicating the total number of processes started
by p4 in all clusters, including all remote masters but not the big master. 



Functions for Cluster Management
================================


The p4 system supports the cluster model of parallel computation, in
which subsets of processes share memory with one another, with the
clusters communicating via messages. A procgroup file for a program
written for the cluster model might look like this: 


 
 
    local                4 
    alliant1.abc.edu     5 /home/me/myprog 
    alliant2.abc.edu     5 /home/me/myprog 
    encore.somewhere.edu 5 /usrs/me/myprog 

This would specify a total of 20 processes, 5 (including the master)
running on the local machine (here assumed to be capable of supporting
five processes that share memory) together with 5 slaves each on three
other shared-memory machines. One process out of each set of remote
slaves will be the ``remote master'' for that cluster.. 


 
 
VOID p4_get_cluster_ids(start,end)      
int *start; 
int *end; 

receives pointers to two integers. It places the p4-assigned id's of the first
and last id's within the current cluster into the two arguments (including
the remote master). 


 
 
int p4_get_my_cluster_id() 

returns a unique id (relative to 0) within a cluster of p4-managed
processes. Thus, a cluster master will always have a cluster id of 0. It is
not clear that a separate cluster id is really useful, but the functionality is
provided just in case. 


 
 
BOOL p4_am_i_cluster_master() 

returns a BOOL value indicating whether the invoking process is the
``cluster master'' process within its cluster. 


 
 
int p4_num_cluster_ids() 

returns an integer value indicating the number of ids in the current cluster
as started by p4_create_procgroup.