p4.tex

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

  -p4version         print current p4 version number
\end{example}

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

\cindex{starting processes by hand}
If one specifies \code{-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.


\node The p4 Function Library, p4 Functions for Managing Processes and Clusters, Command-Line Arguments, Top
\section{The p4 Function Library}




\begin{menu}
* Overview of the Library::
* Return Codes from p4 Functions::
\end{menu}

\node Overview of the Library, Return Codes from p4 Functions, The p4 Function Library, The p4 Function Library
\subsection{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:

\begin{itemize}
\item Functions for managing processes and clusters
\item Functions for message passing
\item Functions for shared memory
\item Functions for timing p4 programs
\item Functions for debugging p4 programs
\item Miscellaneous functions
\item Fortran interface functions
\end{itemize}


\node Return Codes from p4 Functions,  , Overview of the Library, The p4 Function Library
\subsection{Return Codes from p4 Functions}
\cindex{return codes}

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


\node p4 Functions for Managing Processes and Clusters, Functions for Message Passing, The p4 Function Library, Top
\section{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 \code{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 \code{VOID}.  Some of the
procedures return either a pointer to a character string or \code{NULL};
\code{NULL} indicates an error.  The remaining procedures return an
integer value; (-1) indicates an error.





\begin{menu}
* Functions for Process Management::
* Functions for Cluster Management::
\end{menu}

\node Functions for Process Management, Functions for Cluster Management, p4 Functions for Managing Processes and Clusters, p4 Functions for Managing Processes and Clusters
\subsection{Functions for Process Management}
\cindex{process management}

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

\findex{p4_initenv}
\begin{example}
int p4_initenv(argc,argv)
int *argc;
char **argv;
\end{example}
\noindent 
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.  \code{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
\code{argc} to \code{p4_initenv} so that it can actually remove its own
arguments before your program looks at them.

\findex{p4_create}
\begin{example}
int p4_create(fxn)
int (*fxn)();

\findex{p4_create_procgroup}
int p4_create_procgroup()
\end{example}
\noindent
There are two procedures that you can use to create processes in p4,
\code{p4_create_procgroup} and \code{p4_create}.  Processes created via
\code{p4_create} are said to be ``user-managed'' whereas those created
by \code{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 \code{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
\code{p4_create_procgroup} is that you must build a \file{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 \code{p4_create_procgroup} and
\code{p4_create} in the following way: You can use
\code{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.

\code{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 \code{p4_create}.
No other procedures are even aware of their existence.

\code{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 \code{-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 \file{.pg} suffix.  If it
does not find one, it looks for a file named \file{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 \code{p4_startup}.

The effect of \code{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.

\findex{p4_alloc_procgroup}
\begin{example}
struct p4_procgroup *p4_alloc_procgroup()
\end{example}
\noindent
allocates a procgroup data structure of the form described in \code{p4.h}.
The formats of individual entries (\code{p4_procgroup_entry}) are given there
as well. 

\findex{p4_startup}
\begin{example}
int p4_startup(pg)
struct p4_procgroup *pg;
\end{example}
\noindent
starts processes as specified by an an already-created procgroup data
structure allocated by \code{p4_alloc_procgroup} and filled in by the user
using the structures \code{p4_procgroup_entry} and \code{p4_procgroup}.


\findex{p4_wait_for_end}
\begin{example}
VOID p4_wait_for_end()
\end{example}
\noindent
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.

\findex{p4_get_my_id}
\begin{example}
int p4_get_my_id()
\end{example}
\noindent
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.

\findex{p4_num_total_ids}
\begin{example}
int p4_num_total_ids()
\end{example}
\noindent
returns an integer value indicating the total number of ids started
by p4 in all clusters, including the big master and all remote masters.

\findex{p4_num_total_slaves}
\begin{example}
int p4_num_total_slaves()
\end{example}
\noindent
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.


\node Functions for Cluster Management,  , Functions for Process Management, p4 Functions for Managing Processes and Clusters
\subsection{Functions for Cluster Management}
\cindex{cluster management}

The p4 system supports the \dfn{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:

\begin{example}
    local                4
    alliant1.abc.edu     5 /home/me/myprog
    alliant2.abc.edu     5 /home/me/myprog
    encore.somewhere.edu 5 /usrs/me/myprog
\end{example}

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..

\findex{p4_get_cluster_ids}
\begin{example}
VOID p4_get_cluster_ids(start,end)     
int *start;
int *end;
\end{example}
\noindent
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).

\findex{p4_get_my_cluster_id}
\begin{example}
int p4_get_my_cluster_id()
\end{example}
\noindent
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.

\findex{p4_am_i_cluster_master}
\begin{example}
BOOL p4_am_i_cluster_master()
\end{example}
\noindent
returns a BOOL value indicating whether the invoking process is the
``cluster master'' process within its cluster.

\findex{p4_num_cluster_ids}
\begin{example}
int p4_num_cluster_ids()
\end{example}
\noindent
returns an integer value indicating the number of ids in the current
cluster as started by \code{p4_create_procgroup}.  

\findex{p4_cluster_shmem_sync}
\begin{example}
VOID p4_cluster_shmem_sync(cluster_shmem)
VOID **cluster_shmem;
\end{example}
\noindent
This routine is used to synchronize the processes in a cluster before they
begin to use shared memory.

\findex{p4_get_cluster_masters}
\begin{example}
VOID p4_get_cluster_masters(numids, ids)
int *numids, ids[];
\end{example}
\noindent
This procedure fills in the values of \code{numids} and \code{ids}.
It obtains the p4-id's of all ``cluster masters'' for the program, placing
them in the \code{ids} array and placing the number of id's in \code{numids}.


\node Functions for Message Passing, Functions for Shared Memory, p4 Functions for Managing Processes and Clusters, Top
\section{Functions for Message Passing}
\cindex{message-passing functions}

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.





\begin{menu}
* Explicit Sending and Receiving of Messages::
* Global Operations::
\end{menu}

\node Explicit Sending and Receiving of Messages, Global Operations, Functions for Message Passing, Functions for Message Passing
\subsection{Explicit Sending and Receiving of Messages}

\cindex{sending messages}
\findex{p4_send}
\findex{p4_sendr}
\findex{p4_sendx}
\findex{p4_sendrx}
\findex{p4_sendb}
\findex{p4_sendbr}
\findex{p4_sendbx}
\findex{p4_sendbrx}
\begin{example}
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;
\end{example}
\noindent

Each of these procedures sends a message.  The \code{type} argument is an
integer value chosen by the user to represent a message type.  The \code{to}
argument is an integer value that specifies the p4-id of the process that
should receive the message.  The \code{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.  \code{p4_sendb}.  These procedures assume that the
msg is in a buffer that the user obtained earlier via a \code{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 \code{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 \code{datatype} parameter are \code{P4INT},
\code{P4DBL}, \code{P4FLT}, \code{P4LNG}, and \code{P4NOX}.  The last of
these means ``no translation''.


\findex{p4_messages_available}
\begin{example}
BOOL p4_messages_available(req_type,req_from)
int *req_type,*req_from;