p4.txt

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

   unix man page for the Fortran interface to p4 

fiber
   status of the work on direct fiber channel 


The Postscript version of this manual is available by anonymous ftp
from info.mcs.anl.gov, in the directory pub/p4. The file to get (in
binary mode) is p4-manual.ps.Z. There is also a paper there giving an
overview of p4, in p4-paper.ps.Z. This manual is also available through
the World Wide Web at 
http://www.mcs.anl.gov/home/lusk/p4/p4-manual/p4.html.



Examples included with the Distribution
=======================================


A good way to see how various p4 functions are used is to look at the
example programs included in the distribution. The p4/monitors directory
contains shared-memory examples written in C that use monitors,
including one instrumented with ALOG. The p4/messages subdirectory
contains message-passing examples written in C. The programs in 
p4/messages_f are Fortran message-passing examples, and the p4/contrib
and p4/contrib_f directories contain a number of miscellaneous examples
contributed by users. In each directory there is a README that describes
the individual examples. 



Getting Started
***************


The easiest way to get started with p4 is to play with some of the sample
programs provided with the system. 



A Message-Passing Example
=========================


We will begin with a message-passing example in the sub-directory
named p4/messages. The code for the program is in the files sr_test.c and 
sr_user.h. 



Program Description
===================


As the name implies, this program is an example of p4's send/receive
functionality. Briefly, it is a simple program that runs a master process
and some slave processes. The master and the set of slaves form a ring of
processes in which the master reads a message from stdin and sends a
copy of the message to the first slave, which passes it on; the last slave
passes the message back to the master. If the master receives an
undamaged copy of the message, it assumes that all went well, and reads
another message. Note that the ring of processes is a logical structure in
which each process assumes that its predecessor in the ring is the process
with the next lower id, and its successor is the process with the next
higher id. The master has id 0 (zero) and has the process with the largest
id as its predecessor. 



Analysis of the Program
=======================



The first executable p4 statement in a program should be: 

 
 
p4_initenv(&argc,argv);  

This initializes the p4 system and allows p4 to extract any command line
arguments passed to it, e.g. debugging parameters. 

Similarly, the last executable p4 statement in a program should be: 

 
 
p4_wait_for_end();  

This waits for termination of p4 processes and performs some cleanup
operations. 

The procedure p4_get_my_id returns the unique integer id assigned to
the calling process by p4. 

The statement: 

 
 
p4_create_procgroup(); 

reads a procgroup file that the user builds and creates the set of slaves
described in that file. Obviously this statement must be executed before
any slaves can be assumed to exist. This procedure is the method you must
use to create processes that do message-passing. 

The procedure p4_clock returns an integer that represents wall-clock
time in milliseconds. It is typically used to retrieve the time before and
after some work, the difference representing the time to do that work.
Note that there is also a p4_ustimer that is useful on those machines
that support a microsecond timer. 

The procedures p4_send and p4_sendr are two of several p4
procedures that are available for sending messages to other processes.
They take as arguments the message type, the id of the "to" process, the
address of the message, and the message length. 

The procedure p4_recv receives a message from another process and
sets the values of all four parameters. P4_recv will automatically
retrieve a buffer in which to place a received message, thus 
p4_msg_free may be called to free that buffer when it is no longer
needed. 

The procedure p4_num_total_slaves is one of several procedures
that the user can invoke to determine information about the current
execution. 

To run this program, you need to create a procgroup file that describes
where all slave processes are to be executed (See section Specifying
Processes in the Procgroup File). We will assume that you have an
example procgroup file (named sr_test.pg) in the p4/messages directory,
and can run sr_test by merely typing: 

 
 
sr_test 

If the procgroup file is elsewhere, then you must type: 

 
 
sr_test -pg   pathname_of_procgroup_file 

Another example that is made by default is the program systest. It
tests a number of the message-passing features of p4. 



Specifying Processes in the Procgroup File
******************************************


The procgroup file is the only portion of the interface that is very likely
to change through multiple versions of p4. As new architectures are
supported, it is hoped that we can merely alter the procgroup file format
to reflect any new features. (Of course new procedure calls may also be
required, but existing procedure calls will remain unchanged when
possible). See See section Running p4 on Specific Machines for a
discussion of machine dependencies in starting p4 programs. 

The current format of a procgroup file is as follows: 

 
 
local_machine  n [full_path_name] [loginname] 
remote_machine n full_path_name [loginname] 
  . 
  . 
  . 

In some situations, the program is started via some special command
executed from the host machine. In such cases, the procgroup file name
can be specified to the special command line along with the program
name (see for example the runcube and rundelta shell scripts in the 
p4/messages subdirectory). In those cases where no special command is
required, no special handling is required for the procgroup filename. 

The first line of a procgroup file may be ``local n'' where n is the number
of slave processes that share memory with the master. The full path name
on the ``local'' line is ignored on machines other than cube and mesh
machines, and the IBM SP-1. The word ``local'' may be replaced by an
alias for the local machine if needed, to specify an alternative transport
layer. The subsequent lines contain either three or four fields: 


   1. the name of a remote machine on which slave processes are to
   be created. 
   2. the number of slaves that are to be created on that machine, i.e.
   be in the same cluster (note that on machines that support it, the
   processes in a cluster will share memory) 
   3. the full path name of the executable slave program 
   4. optionally, the user login name on the remote machine, if
   different from that on the host machine. 


As an example, let's assume that you have a network of three Sun
workstations named sun1, sun2, and sun3. We will also assume that you
are working on sun1 and plan to run a master process there. If you would
like to run one process on each of the other Suns, then you might code a
procgroup file that looks like: 


 
 
    # start one slave on each of sun2 and sun3 
    local 0  
    sun2  1  /home/mylogin/p4pgms/sr_test 
    sun3  1  /home/mylogin/p4pgms/sr_test 

Lines beginning with # are comments. 

It is also possible to have different executables on different machines.
This is required, of course, when the machines don't share files or are of
different architectures. An example of such a procgroup file would be: 


 
 
    local   0 
    sun2    1  /home/user/p4pgms/sun/prog1 
    sun3    1  /home/user/p4pgms/sun/prog2 
    rs6000  1  /home/user/p4pgms/rs6000/prog1 

On a shared memory machine such as a KSR, in which you want all the
processes to communicate through shared memory using monitors, the
procgroup file can be as simple as: 


 
 
    local 50 

On the CM-5, your procgroup file would look like: 


 
 
    local 32 /home/joe/p4progs/cm5/multiply 

Next, let's assume that you have a Sequent Symmetry (named symm) and
an Encore Multimax (named mmax). We will also assume that you are
working on symm, and plan to run the master there. If you would like to
run two processes on symm (in addition to the master) and two on mmax,
then you might code a procgroup file that looks like: 


 
 
    local 2  
    mmax  2  /mmaxfs/mylogin/p4pgms/sr_test 

P4 also permits you to treat the symmetry as a remote machine even when
you are running the master there. Thus, you might code a procgroup file
as follows: 


 
 
    local 2  
    symm  2  /symmfs/mylogin/p4pgms/sr_test 
    mmax  2  /mmaxfs/mylogin/p4pgms/sr_test 

In this example, there are seven processes running. Five of the processes
are on symm, including the master. Two of the processes on symm are in
the master's procgroup and two are running in a separate procgroup as if
they were on a separate machine. Of course, the last two are running on
mmax. 

Finally, suppose that you have a fiber-channel network that parallels your
Ethernet, connecting the same machines, and that connections fro running
TCP/IP over the fiber-channel network are obtained by connecting to 
sun1-fc, sun2-fc, etc. Then even if sun1 is the local machine that
you are logged into, you will want your procgroup file to look like: 


 
 
    sun1-fc    0 
    sun2-fc    1  /home/user/p4pgms/sun/prog1 
    sun3-fc    1  /home/user/p4pgms/sun/prog2 

Some notes about the contents of the procgroup file should be made at
this point. First, the value of n on the local line can be zero, i.e. the
master may have no local slaves. Second, the local machine may be
treated as if it is a remote machine by merely entering it in some line as a
remote machine. Third, a single machine may be treated as multiple
remote machines by having the same remote machine name entered on
multiple lines in the procgroup file. Fourth, if a single machine is listed
multiple times, those processes specified on each line form a single
cluster (share memory). Fifth, the cluster size specified for a uniprocessor
should be 1, because all slaves in a cluster are assumed to run in parallel
and to share memory. 

We refer to the original (master) process as the ``big master''. The first
process created in each cluster is the ``remote master'' or the ``cluster
master'' for that cluster. All p4-managed processes (see the procedure 
p4_create_procgroup) have unique integer id's beginning with 0.
The processes within a cluster are numbered consecutively. 



Developing a Simple p4 Program
******************************


The real fun associated with any computing environment arrives when
you actually type in a program and run it yourself. We will assume that
you have successfully installed p4 on your own system and are ready to
write a small program, compile it, and run it. 



A Minimal Example
=================


We will start with a tiny program in which the worker processes do no
work, and then expand its capabilities. Edit a file called p4simple.c and
type: 


 
 

#include "p4.h" 

main(argc,argv) 
    int argc; 
    char **argv; 
    { 
        p4_initenv(&argc,argv); 
        p4_create_procgroup(); 
        worker(); 
        p4_wait_for_end(); 
    } 

worker() 
    { 
        printf("Hello from %d\n",p4_get_my_id()); 
    } 


This is one of the simplest p4 programs that you can write. Let's examine
it. The #include "p4.h" statement must appear in all programs that
use any p4 features. The procedure p4_initenv must be invoked
before any other p4 procedures, and p4_wait_for_end must be
invoked after all p4 processing is completed. The p4_get_my_id
returns a unique integer id for each process, beginning with 0. The
procedure p4_create_procgroup is responsible for creating all
processes other than 0. It has no effect if called by any other processes
than process 0. The way in which p4_create_procgroup
determines how many other processes there should be, and where they
should run, will be discussed shortly. 

All processes that this program executes invoke the worker procedure,
including process 0. Thus, in this program, the master process acts just
like all other processes once it gets the environment established. 

To understand how things get started, let's consider two separate
situations. In the first situation, all processes are running on a single
machine. Then, when process 0 starts, it executes the 
p4_create_procgroup procedure to start all other slaves. The other
slaves are started on the same machine by means of a UNIX fork. 

In the second situation, there may be slaves running both on the same
machine as process 0, and slaves running on other machines as well. In
this situation, the first slave running on a remote machine will need to
execute the main procedure. It will discover that it is not process 0.
However, as part of initialization, process 0 will direct it to fork any
additional slaves required on the same machine. 

In some ways, the above example can be used as a prototype for all p4
programs, just by varying the content of the worker routine. 



A Minimal Example in Fortran
============================


Here is a Fortrran version of the program we just discussed. 

 
 
      program p4simple 
      include 'p4f.h' 

call p4init() 
      call p4crpg() 
      call fworker() 
      call p4cleanup() 
      stop 
      end 

subroutine fworker() 
      include 'p4f.h' 
      integer*4 procid 

procid = p4myid() 
      print *,'Hello from ',procid 

end 



A More Complicated Example
==========================


Now, let's make the worker process a little bit more interesting. Let's
assume that we have nprocs slaves with ids 0, 1, 2, ... nprocs -1.
And, we want to write a program in which every process sends a single
message to every other slave, and then receives a message from every
other slave. We might alter the code for the worker procedure to be the
following: 


 
 
    worker() 
    { 
        char *incoming, *msg = "hello";