diff --git a/ompi/mpi/man/man3/MPI_Init_thread.3in b/ompi/mpi/man/man3/MPI_Init_thread.3in index ead079b875..aecb261c6b 100644 --- a/ompi/mpi/man/man3/MPI_Init_thread.3in +++ b/ompi/mpi/man/man3/MPI_Init_thread.3in @@ -1,13 +1,15 @@ +. -*- nroff -*- .\"Copyright 2006-2008 Sun Microsystems, Inc. .\" Copyright (c) 1996 Thinking Machines Corporation +.\" Copyright (c) 2010 Cisco Systems, Inc. All rights reserved. .TH MPI_Init_thread 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#" - +. .SH NAME \fBMPI_Init_thread\fP \- Initializes the MPI execution environment - +. .SH SYNTAX .ft R - +. .SH C Syntax .nf #include @@ -37,7 +39,8 @@ C/C++ only: Argument vector. .TP 1i required Desired level of thread support (integer). - +. +. .SH OUTPUT PARAMETERS .ft R .TP 1i @@ -46,7 +49,8 @@ Available level of thread support (integer). .TP 1i IERROR Fortran only: Error status (integer). - +. +. .SH DESCRIPTION .ft R This routine, or MPI_Init, must be called before any other MPI routine @@ -70,7 +74,8 @@ calls at one time. MPI_THREAD_MULTIPLE If the process is multithreaded, multiple threads may call MPI at once with no restrictions. -.SH +. +.PP The level of thread support available to the program is set in \fIprovided\fP, except in C++, where it is the return value of the function. In Open MPI, the value is dependent on how the library was configured and built. Note that there is no guarantee that \fIprovided\fP will be greater than or equal to @@ -90,7 +95,7 @@ them: MPI_Finalize(); } .fi - +. .SH NOTES .ft R The Fortran version does not have provisions for \fIargc\fP and @@ -104,7 +109,58 @@ MPI_Init_thread or after an MPI_Finalize. In the Open MPI implementation, it should do as little as possible. In particular, avoid anything that changes the external state of the program, such as opening files, reading standard input, or writing to standard output. - +. +. +.SH MPI_THREAD_MULTIPLE Support +. +MPI_THREAD_MULTIPLE support is included if Open MPI was configured +with the --enable-thread-multiple configure switch. You can check the +output of +.BR ompi_info (1) +to see if Open MPI has MPI_THREAD_MULTIPLE support: +. +.PP +.nf +shell$ ompi_info | grep -i thread + Thread support: posix (mpi: yes, progress: no) +shell$ +.fi +. +.PP +The "mpi: yes" portion of the above output indicates that Open MPI was +compiled with MPI_THREAD_MULTIPLE support. +. +.PP +Note that MPI_THREAD_MULTIPLE support is only lightly tested. It +likely does not work for thread-intensive applications. Also note +that +.I only +the MPI point-to-point communication functions for the BTL's listed +below are considered thread safe. Other support functions (e.g., MPI +attributes) have not been certified as safe when simultaneously used +by multiple threads. +. +.PP +.nf + tcp + sm + mx + elan + self +.fi +. +.PP +Note that Open MPI's thread support is in a fairly early stage; the +above devices are likely to +.IR work , +but the latency is likely to be fairly high. Specifically, efforts so +far have concentrated on +.IR correctness , +not +.I performance +(yet). +. +. .SH ERRORS .ft R Almost all MPI routines return an error value; C routines as @@ -119,7 +175,7 @@ I/O function errors. The error handler may be changed with MPI_Comm_set_errhandler; the predefined error handler MPI_ERRORS_RETURN may be used to cause error values to be returned. Note that MPI does not guarantee that an MPI program can continue past an error. - +. .SH SEE ALSO .ft R .nf diff --git a/orte/tools/orterun/orterun.1in b/orte/tools/orterun/orterun.1in index a086f485d4..983b938ff9 100644 --- a/orte/tools/orterun/orterun.1in +++ b/orte/tools/orterun/orterun.1in @@ -1,5 +1,7 @@ +. -*- nroff -*- .\" Copyright (c) 2009 Cisco Systems, Inc. All rights reserved. .\" Copyright (c) 2008-2009 Sun Microsystems, Inc. All rights reserved. +.\" Copyright (c) 2010 Cisco Systems, Inc. All rights reserved. .\" .\" Man page for ORTE's orterun command .\" @@ -1031,13 +1033,16 @@ signal), \fImpirun\fP will print out an error message and kill the rest of the MPI application. .PP User signal handlers should probably avoid trying to cleanup MPI state -(Open MPI is, currently, neither thread-safe nor async-signal-safe). -For example, if a segmentation fault occurs in \fIMPI_SEND\fP (perhaps because -a bad buffer was passed in) and a user signal handler is invoked, if this user -handler attempts to invoke \fIMPI_FINALIZE\fP, Bad Things could happen since -Open MPI was already "in" MPI when the error occurred. Since \fImpirun\fP -will notice that the process died due to a signal, it is probably not -necessary (and safest) for the user to only clean up non-MPI state. +(Open MPI is currently not async-signal-safe; see MPI_Init_thread(3) +for details about +.I MPI_THREAD_MULTIPLE +and thread safety). For example, if a segmentation fault occurs in +\fIMPI_SEND\fP (perhaps because a bad buffer was passed in) and a user +signal handler is invoked, if this user handler attempts to invoke +\fIMPI_FINALIZE\fP, Bad Things could happen since Open MPI was already +"in" MPI when the error occurred. Since \fImpirun\fP will notice that +the process died due to a signal, it is probably not necessary (and +safest) for the user to only clean up non-MPI state. . . . @@ -1202,18 +1207,19 @@ Be sure also to see the examples throughout the sections above. . .TP 4 mpirun -np 4 -mca btl ib,tcp,self prog1 -Run 4 copies of prog1 using the "ib", "tcp", and "self" BTL's for the transport -of MPI messages. +Run 4 copies of prog1 using the "ib", "tcp", and "self" BTL's for the +transport of MPI messages. . . .TP 4 mpirun -np 4 -mca btl tcp,sm,self .br ---mca btl_tcp_if_include ce0 prog1 +--mca btl_tcp_if_include eth0 prog1 .br -Run 4 copies of prog1 using the "tcp", "sm" and "self" BTLs for the transport of -MPI messages, with TCP using only the ce0 interface to communicate. Note that -other BTLs have similar if_include MCA parameters. +Run 4 copies of prog1 using the "tcp", "sm" and "self" BTLs for the +transport of MPI messages, with TCP using only the eth0 interface to +communicate. Note that other BTLs have similar if_include MCA +parameters. . .\" ************************** .\" Diagnostics Section @@ -1243,5 +1249,5 @@ be the first rank that died but is not guaranteed to be so. .\" See Also Section .\" ************************** . -.\" .SH SEE ALSO -.\" orted(1), ompi-server(1) +.SH SEE ALSO +MPI_Init_thread(3)