p4.tex

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

    local 0 
    sun2  1  /home/mylogin/p4pgms/sr_test
    sun3  1  /home/mylogin/p4pgms/sr_test
\end{example}

Lines beginning with \code{#} 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:

\begin{example}
    local   0
    sun2    1  /home/user/p4pgms/sun/prog1
    sun3    1  /home/user/p4pgms/sun/prog2
    rs6000  1  /home/user/p4pgms/rs6000/prog1
\end{example}

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:

\begin{example}
    local 50
\end{example}

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

\begin{example}
    local 32 /home/joe/p4progs/cm5/multiply
\end{example}

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

\begin{example}
    local 2 
    mmax  2  /mmaxfs/mylogin/p4pgms/sr_test
\end{example}

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:

\begin{example}
    local 2 
    symm  2  /symmfs/mylogin/p4pgms/sr_test
    mmax  2  /mmaxfs/mylogin/p4pgms/sr_test
\end{example}

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
\code{sun1-fc}, \code{sun2-fc}, etc.  Then even if \code{sun1} is the local
machine that you are logged into, you will want your procgroup file to look
like:


\begin{example}
    sun1-fc    0
    sun2-fc    1  /home/user/p4pgms/sun/prog1
    sun3-fc    1  /home/user/p4pgms/sun/prog2
\end{example}

Some notes about the contents of the procgroup file should be made at
this point.  First, the value of \code{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 \code{p4_create_procgroup}) 
have unique integer id's beginning with 0.
The processes within a cluster are numbered consecutively.



\node Developing a Simple p4 Program, Command-Line Arguments, Specifying Processes in the Procgroup File, Top
\section{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.




\begin{menu}
* A Minimal Example::
* A Minimal Example in Fortran::
* A More Complicated Example::
\end{menu}

\node A Minimal Example, A Minimal Example in Fortran, Developing a Simple p4 Program, Developing a Simple p4 Program
\subsection{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 \file{p4simple.c} and type:

\begin{example}

    #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\verb+\+n",p4_get_my_id());
    \}

\end{example}

This is one of the simplest p4 programs that you can write.  Let's examine it.
The \code{#include "p4.h"} statement must appear in all programs that use any
p4 features.  The procedure \code{p4_initenv} must be invoked before any other
p4 procedures, and \code{p4_wait_for_end} must be invoked after all p4
processing is completed.  The \code{p4_get_my_id} returns a unique integer id
for each process, beginning with 0.  The procedure \code{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
\code{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
\code{p4_create_procgroup} procedure to start all other slaves.  The other
slaves are started on the same machine by means of a UNIX \code{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 \code{worker} routine.

\node A Minimal Example in Fortran, A More Complicated Example, A Minimal Example, Developing a Simple p4 Program
\subsection{A Minimal Example in Fortran}

Here is a Fortrran version of the program we just discussed.
\begin{example}
      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
\end{example}



\node A More Complicated Example,  , A Minimal Example in Fortran, Developing a Simple p4 Program
\subsection{A More Complicated Example}

Now, let's make the worker process a little bit more interesting.  Let's
assume that we have \code{nprocs} slaves with ids 
0, 1, 2, ... \code{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:

\begin{example}
    worker()
    \{
        char *incoming, *msg = "hello";
        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);
        \}
    \}
\end{example}

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 \code{p4_send} call requires 4 arguments:
\begin{itemize}
\item a message type (arbitrarily chosen to be 100 here)
\item the id of the process to receive the message
\item the message itself
\item the size of the message
\end{itemize}

The use of \code{p4_recv} is slightly more complicated.  First, we assign -1
to each of the parameters \code{type} and \code{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 \code{i} each time through the loop
(skipping our own id).  By setting \code{incoming} to NULL, we have also
indicated to \code{p4_recv} that we do not have a buffer in which to place the
received message, so \code{p4_recv} should obtain a buffer for us and place
the message in that buffer.  \code{p4_recv} treats these three parameters as
both input and output values.  Thus, it alters the value of each such that
\code{type} and \code{from} indicate the type of message received and the id
of the process that sent it.  The value of \code{incoming} is altered to point
to the buffer where the message was placed.  The \code{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.

\cindex{deallocating buffers}
Finally, note that \code{p4_msg_free} frees the message buffer obtained by
\code{p4_recv.} The procedure \code{p4_msg_free} should be called only after
the contents of the message are no longer needed.  \code{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
\file{/usr/local/p4} and that you have typed the program above into a
file name \file{p4simple.c} in the directory
\file{/home/mylogin/p4pgms}.

To build your makefile, copy the file
\begin{example}
    /usr/local/p4/messages/makefile.proto
\end{example}
\noindent
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 \code{sr_test}.  Do a global change of
\code{sr_test} to \code{p4simple}.  You should also change the value of
\code{P4_HOME_DIR}.  It should contain the full
pathname of the p4 system, e.g. \file{/usr/local/p4}.  Now change
directories to \file{/usr/local/p4} and type:

\begin{example}
make makefiles P4ARCH=<machine_type> DIRS=/home/mylogin/p4pgms
\end{example}
\noindent
where \code{<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 \file{Makefile} there.  
You should then be able to type:

\begin{example}
    make p4simple
\end{example}

There is one last piece missing before you can execute your program.  Recall
that \code{p4_create_procgroup} needs to know how many processes to start and
where to start them; it reads a file (called a \dfn{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 \code{<progname>.pg} is the
default name.  For example, in this case your procgroup file should be named
\file{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:

\begin{example}
    local O
    some.network.machine 1 /home/me/p4progs/p4simple
\end{example}

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 \code{some.network.machine}.

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

\begin{example}
    p4simple
\end{example}

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 \code{strip} to reduce
the size or removing \code{-g} from the CFLAGS in the makefile.


\node Command-Line Arguments, The p4 Function Library, Developing a Simple p4 Program, Top
\section{Command-Line Arguments}
\cindex{command-line arguments}

The command-line arguments to a p4 program are all optional.
\begin{example}
  -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