p4.txt

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

User's Guide to the p4 Parallel Programming System
**************************************************


This is both the reference manual and the User's Guide for the p4 parallel
programming system. It contains definitions of all functions for both C
and Fortran, examples, a brief tutorial, and discussions of related systems.

Ralph Butler
++++++++++++

and 

Ewing Lusk
++++++++++


Function Index 


Contents 

 o Introduction 
 o Structure of the Distribution Directory 
 o Installing p4 
    o Installing the p4 System 
    o Installing the Documentation 
    o Examples included with the Distribution 
 o Getting Started 
    o A Message-Passing Example 
    o Program Description 
    o Analysis of the Program 
 o Specifying Processes in the Procgroup File 
 o Developing a Simple p4 Program 
    o A Minimal Example 
    o A Minimal Example in Fortran 
    o A More Complicated Example 
 o Command-Line Arguments 
 o The p4 Function Library 
    o Overview of the Library 
    o Return Codes from p4 Functions 
 o p4 Functions for Managing Processes and Clusters 
    o Functions for Process Management 
    o Functions for Cluster Management 
 o Functions for Message Passing 
    o Explicit Sending and Receiving of Messages 
    o Global Operations 
 o Functions for Shared Memory 
    o Managing Shared and Local Memory 
    o Shared Memory Data Types 
    o Monitor-Building Primitives 
    o Some Useful Monitors 
 o Functions for Timing p4 Programs 
 o Functions for Debugging p4 Programs 
 o Miscellaneous Functions 
 o Fortran Interface 
 o Faster Startup with the Secure Server 
 o Utilities for Managing a p4 Session 
 o Creating Logfiles for Upshot 
    o User-Specified Events 
    o Creating Log Files in Fortran 
    o Examining Log Files with Upshot 
    o Automatic Logging of p4 Events 
 o Running p4 on Specific Machines 
    o Invoking a p4 Program 
    o Machine-Specific Notes 
 o Some Common Problems and their Solutions 
 o Concept Index 
 o Function Index 



Introduction
************


P4 is a library of macros and subroutines developed at Argonne National
Laboratory for programming a variety of parallel machines. A paper
describing its functions and use is [(ref butler-lusk:p4-paper)]. Its
predecessor was the m4-based ``Argonne macros'' system described in
the Holt, Rinehart, and Winston book Portable Programs for Parallel
Processors, by Lusk, Overbeek, et al., from which p4 takes its name[(ref
lusk-overbeek:p4-book)]. The current p4 system maintains the same
basic computational models described there (monitors for the
shared-memory model, message-passing for the distributed-memory
model, and support for combining the two models) while significantly
increasing ease and flexibility of use. See section Getting Started for a
simple example. 

P4 is intended to be portable, simple to install and use, and efficient. It
can be used to program networks of workstations, advanced parallel
supercomputers like the Intel Touchstone Delta and the Alliant Campus
HiPPI-based system, and single shared-memory multiprocessors. It has
currently been installed on the following list of machines: Sequent
Symmetry (Dynix and PTX), Convex, Encore Multimax, Alliant FX/8,
FX/800, and FX/2800, Cray X/MP, Sun (SunOS and Solaris), NeXT,
DEC, Silicon Graphics, HP, and IBM RS6000 workstations, Stardent
Titan, BBN GP-1000 and TC-2000, Kendall Square, nCube, Intel
IPSC/860, Intel Touchstone Delta, Intel Paragon, Alliant Campus,
Thinking Machines' CM-5, and the IBM SP-1 (TCP/Ethernet,
TCP/switch, EUI, and EUI-H). It is not difficult to port to new systems.
Although p4 tries to be completely portable, there are a small number of
specific exceptions (See section Machine-Specific Notes) that may need
to be taken into account on a given machine. 

You can obtain the complete distribution of p4 by anonymous ftp from 
info.mcs.anl.gov in the directory pub/p4. See the README file
there for recent news on what is available. Take the file p4-1.4.tar.Z. The
distribution contains all source code, installation instructions, this
reference manual, and a collection of examples in both C and Fortran. 
Alog is included in the distribution with p4. The file upshot.tar.Z
contains display facilities that can be used with p4 and other systems. 

To ask questions about p4, report bugs, contribute examples, etc., you can
send mail to [e-mail]. 

The current release is version 1.4. You can check which version of the
source code you have by looking at the file lib/p4_patchlevel.h in the
distribution. You can check which version of the object code you have
linked to by running any p4 program with the command-line option 
-p4version (See section Command-Line Arguments). 

Salient features of p4 include: 

 o support for both message-passing and explicit shared memory
   operations 
 o xdr support for heterogeneous networks 
 o World Wide Web version of the manual for on-line help 
 o SYSV IPC support for shared-memory multiprocessing on
   workstations that support multiple processors, and simulating it
   on uniprocessors 
 o instrumentation for automatic logging/tracing 
 o automatic or user control of message-passing/buffer-management
 o error/interrupt handling 
 o an optional p4 server for quick startup on remote machines 


A useful companion system is the alog/upshot logging and X-based
trace examination facility. (See section Creating Logfiles for Upshot.) 



Structure of the Distribution Directory
***************************************


The p4 source code distribution contains the following files and
subdirectories: 

CHANGES
   Changes new to this release of p4. 
Makefile
   The makefile for making the p4 system, doing the installation, and
   making makefiles for user applications. 
OPTIONS
   A file controlling various compile-time options, such as whether
   System V shared-memory operations are to be enabled, whether
   system debug message printing is to be enabled, and whether
   automatic instrumentation of internal p4 operations for the 
   upshot logging and tracing program is to be done. It also
   contains the full pathname of the listener to be used. 
README
   General instructions, including how to build and install pr. 
alog
   Source code for the ALOG tracing package. 
bin
   Scripts for starting and killing servers, killing runaway p4
   processes, merging upshot logfiles, and other useful utilities. 
contrib
   Examples contributed by p4 users. 
contrib_f
   Fortran examples contributed by users. 
doc
   The man page, together with this manual and supporting files,
   including a reference card for p4 routines. 
include
   The include directory for making p4 applications. Most of these
   are (hard) links into the lib directory. 
lib
   The source code for the p4 system. 
lib_f
   The Fortran interface for p4. 
messages
   A basic set of message-passing examples in C. 
messages_f
   A basic set of message-passing examples in Fortran. 
misc
   A few odds and ends of programs that fit no special category.
   Some of these have been found useful during debugging. 
monitors
   A basic set of shared-memory examples in C. 
servers
   The secure and insecure servers. 
usc
   The portable microsecond clock routines. 
util
   Assorted supporting files, particularly for making the p4
   distribution. 




Installing p4
*************


In this section we describe how to install the p4 library, either for your
own personal use or for the use of everyone at your site. In the first case
you do not need any super-user privileges. In the second case, you may or
may not, depending on how things are configured at your site. We also
describe how to install and run the examples that come with p4, the
online help system (this manual as a World Wide Web document) and
how to build a working directory for your own programs yet share the
installed copy of p4 with other users. 



Installing the p4 System
========================


To build p4, position yourself in the top-level p4 directory (Here we
refer to this directory as p4, but you may have it as p4-1.4 or
something similar) and type: 

 
 
make all P4ARCH=<machine> 

where <machine> is one of the machine names listed in p4/util/machines,
currently: 

SUN
   Sun-3, Sun386i, Sparc-1, Sparc-2, or Sparc-10 workstations,
   running SunOS 

SUN_SOLARIS
   Sun workstations running Solaris 

HP
   HP workstations 

DEC5000
   Dec 5000 workstations 

ALPHA
   Dec Alpha workstations 

NEXT
   68030- or 68040-based NeXT workstations 

RS6000
   IBM RS 6000 series workstations 

LINUX
   IBM-compatible PC's running the LINUX operating system 

IBM3090
   IBM 3090 running IBM's version of UNIX, AIX 

BALANCE
   Sequent Balance shared-memory multiprocessor 

SYMMETRY
   Sequent Symmetry shared-memory multiprocessor 

SYMMETRY_PTX
   Sequent Symmetry shared-memory multiprocessor PTX OS 

MULTIMAX
   Encore Multimax shared-memory multiprocessor 

GP_1000
   BBN GP-1000 

TC_2000
   BBN TC-2000 

TC_2000_TCMP
   BBN TC-2000 with the TCMP message-passing library 

IPSC860
   Intel IPSC/860 (nodes only) 

IPSC860_SOCKETS
   Intel IPSC/860 with socket libraries on the nodes 

DELTA
   Intel DELTA 

PARAGON
   Intel Paragon 

TITAN
   Stardent Titan 

SGI
   Silicon Graphics workstations 

CRAY
   Cray X/MP 

FX8
   Alliant FX/8 

FX2800
   Alliant FX/2800 or FX/800 

FX2800_SWITCH
   Alliant FX/2800 or FX/800, with CAMPUS HiPPI switch 

KSR
   Kendall Square KSR-1 

CM-5
   Thinking Machines' CM-5 

SP1
   IBM SP-1 with TCP interface to either Ethernet or switch 

SP1_EUI
   IBM SP-1 with IBM's EUI interface to the switch 

SP1_EUIH
   IBM SP-1 with IBM's experimental EUI-H switch interface 

MEIKO_CS2
   Meiko Computing Surface 


For example: 

 
 
make all P4ARCH=SYMMETRY 

The all is optional, for example 

 
 
make P4ARCH=SYMMETRY 

This will create a machine-dependent Makefile in each subdirectory,
make the p4 library, and compile and link a subset of the examples. 

To add a new machine type, or to change the characteristic parameters
associated with an existing one, you can edit the file p4/util/defs.all. 

To save disk space, various intermediate object files can be removed with 

 
 
make clean 

The system can be restored to its original, machine-independent state
with 

 
 
make realclean 

Note that this removes the machine-dependent Makefiles in each
directory, so the operation is not idempotent. 

It is also possible to install (or clean) only some of the directories: 

 
 
make all P4ARCH=SUN DIRS=messages 
make clean DIRS='monitors messages' 

To install only the Makefiles in all subdirectories, use: 

 
 
make makefiles P4ARCH=<machine> 

To install the necessary library and include files in a directory everything
that is needed to compile and link p4 programs, do: 


 
 
make install INSTALLDIR=<dir> 

This will create a p4 directory in <dir>, build a minimal set of
directories, copy the relevant .a and .h files into it, and test the
installation by mking a small set of examples. 

See section Getting Started for instructions on how to run some example
programs after you have installed p4. 



Installing the Documentation
============================


The directory p4/doc contains this manual as well as files that require
installation. This manual was prepared with the latexinfo package
from GNU emacs. The files in p4/doc are: 

p4.tex
   the latex source for this manual, which uses the latexinfo style 

latexinfo.sty, titlepage.sty
   the style files needed to latex this manual 

p4.html
   an html version of this manual, suitable for being installed in your
   World Wide Web pages. 

p4.txt
   plain ascii text of the manual, in case nothing else works. 

p4refcard.ps
   postscript version of a reference card 

p4.1
   unix man page for the p4 library 

p4f.1