Update the manpages for comm_spawn(_multiple) - add man page to explain host/hostfile behavior

This commit was SVN r18961.

ompi/mpi/man/man3/MPI_Comm_spawn.3

@@ -101,12 +101,13 @@ The following keys for \fIinfo\fP are recognized in Open MPI. (The reserved valu
 Key                   Type      Description
 ---                   ----      -----------
 
-host                  char *    Host on which the process should be spawned.
+host                  char *    Comma-deliminated list of hosts upon which
-                                See the \fIorte_host\fP man page for an
+                                the process(es) should be spawned.
+                                See the \fIorte_hosts\fP man page for an
                                 explanation of how this will be used.
 hostfile              char *    Hostfile containing the hosts on which
-                                the processes are to be spawned. See
+                                the process(es) are to be spawned. See
-                                the \fIorte_hostfile\fP man page for an
+                                the \ fIorte_hosts\fP man page for an
                                 explanation of how this will be used.
 wdir                  char *    Directory where the executable is located.
 ompi_prefix           char *    Same as the --prefix command line argument

ompi/mpi/man/man3/MPI_Comm_spawn_multiple.3

@@ -1,6 +1,6 @@
 .\"Copyright 2006, Sun Microsystems, Inc.
 .\" Copyright (c) 1996 Thinking Machines Corporation
-.TH MPI_Comm_spawn_multiple 3OpenMPI "September 2006" "Open MPI 1.2" " "
+.TH MPI_Comm_spawn_multiple 3OpenMPI "July 2008" "Open MPI 1.3" " "
 .SH NAME
 \fBMPI_Comm_spawn_multiple\fP \- Spawns multiple binaries, or the same binary with multiple sets of arguments. 
 
@@ -105,20 +105,30 @@ Error codes are treated as for MPI_Comm_spawn.
 
  
 .SH INFO ARGUMENTS
-The following keys for \fIinfo\fP are recognized in Open MPI 1.2. (The reserved values mentioned in Section 5.3.4 of the MPI-2 standard are not implemented.)
+The following keys for \fIinfo\fP are recognized in Open MPI 1.3. (The reserved values mentioned in Section 5.3.4 of the MPI-2 standard are not implemented.)
 .sp
 .sp
 .nf
 Key                   Type      Description
 ---                   ----      -----------
 
-host                  char *    Host on which the process should be spawned.
+host                  char *    Comma-deliminated list of hosts upon which
+                                the process(es) should be spawned.
+                                See the \fIorte_hosts\fP man page for an
+                                explanation of how this will be used.
+hostfile              char *    Hostfile containing the hosts on which
+                                the process(es) are to be spawned. See
+                                the \ fIorte_hosts\fP man page for an
+                                explanation of how this will be used.
 wdir                  char *    Directory where the executable is located.
 ompi_prefix           char *    Same as the --prefix command line argument
                                 to mpirun.
 ompi_non_mpi          bool      If set to true, launching a non-MPI
                                 application; the returned communicator
-                                will be MPI_COMM_NULL.
+                                will be MPI_COMM_NULL. Failure to set
+                                this flag when launching a non-MPI
+                                application will cause both the child
+                                and parent jobs to "hang".
 .fi
 
 .sp 
@@ -137,7 +147,7 @@ to true, but others are set to false (or are unset), MPI_ERR_INFO will
 be returned.
   
 .sp
-Note that in Open MPI 1.2, the first array location in \fIarray_of_info\fP is applied to all the commands in \fIarray_of_commands\fP. 
+Note that in Open MPI 1.e, the first array location in \fIarray_of_info\fP is applied to all the commands in \fIarray_of_commands\fP. 
 
 .SH NOTES
 The argument \fIcount\fP is interpreted by MPI only at the root, as is \fIarray_of_argv\fP. Since the leading dimension of \fIarray_of_argv\fP is \fIcount\fP, a nonpositive value of \fIcount\fP at a nonroot node could theoretically cause a runtime bounds check error, even though \fIarray_of_argv\fP should be ignored by the subroutine. If this happens, you should explicitly supply a reasonable value of \fIcount\fP on the nonroot nodes. 

orte/util/Makefile.am

@@ -19,7 +19,11 @@
 # This makefile.am does not stand on its own - it is included from orte/Makefile.am
 
 dist_pkgdata_DATA += util/hostfile/help-hostfile.txt \
-	util/dash_host/help-dash-host.txt
+                     util/dash_host/help-dash-host.txt
+
+man_MANS = util/hostfile/orte_hosts.7
+
+EXTRA_DIST = $(man_MANS)
 
 AM_LFLAGS = -Porte_util_hostfile_
 LEX_OUTPUT_ROOT = lex.orte_util_hostfile_

orte/util/hostfile/orte_hosts.7

@@ -0,0 +1,69 @@
+.\"
+.\" Copyright (c) 2008	Los Alamos National Security, LLC  All rights reserved.
+.\"
+.\" Man page for ORTE's Hostfile functionality
+.\" 
+.\" .TH name     section center-footer   left-footer  center-header
+.TH     ORTE_HOSTS  7       "July 2008" "OpenRTE"   "OPENRTE HOSTS OVERVIEW"
+.\" **************************
+.\"    Name Section
+.\" **************************
+.SH NAME
+.
+OpenRTE Hostfile and HOST Behavior \- Overview of OpenRTE's support for user-supplied hostfiles and comma-delimited lists of hosts
+.
+.\" **************************
+.\"    Description Section
+.\" **************************
+.SH DESCRIPTION
+.
+.PP
+OpenRTE supports several levels of user-specified host lists based on an established
+precedence order. Users can specify a \fIdefault hostfile\fP that contains a list of
+nodes available to all app_contexts given on the command line. Only \fIone\fP default
+hostfile can be provided for any job. In addition, users
+can specify a \fIhostfile\fP that contains a list of nodes to be used for a specific
+app_context, or can provide a comma-delimited list of nodes to be used for that
+app_context via the \fI-host\fP command line option.
+.sp
+The precedence order applied to these various options depends to some extent on
+the local environment. The following table illustrates how host and hostfile directives
+work together to define the set of hosts upon which a job will execute
+in the absence of a resource manager (RM):
+.sp
+.nf
+ default
+ hostfile      host        hostfile       Result
+----------    ------      ----------      -----------------------------------------
+ unset        unset          unset        Job is co-located with mpirun
+ unset         set           unset        Host defines resource list for the job
+ unset        unset           set         Hostfile defines resource list for the job
+ unset         set            set         Hostfile defines resource list for the job,
+                                          then host filters the list to define the final
+                                          set of nodes available to each application
+                                          within the job
+  set         unset          unset        Default hostfile defines resource list for the job
+  set          set           unset        Default hostfile defines resource list for the job,
+                                          then host filters the list to define the final
+                                          set of nodes available to each application
+                                          within the job
+  set          set            set         Default hostfile defines resource list for the job,
+                                          then hostfile filters the list, and then host filters
+                                          the list to define the final set of nodes available
+                                          to each application within the job
+.fi
+.sp
+This changes somewhat in the presence of a RM as that entity specifies the
+initial allocation of nodes. In this case, the default hostfile, hostfile and host
+directives are all used to filter the RM's specification so that a user can utilize different
+portions of the allocation for different jobs. This is done according to the same precedence
+order as in the prior table, with the RM providing the initial pool of nodes.
+.sp
+.
+.\" **************************
+.\"    See Also Section
+.\" **************************
+.
+.SH SEE ALSO
+  orterun(1)
+.