S3L_thread_comm_setup

Description

S3L_thread_comm_setup establishes the appropriate internal MPI communicators and data for thread-safe operation of S3L functions. It should be called from each thread in which S3L functions will be used.

Only S3L_init can be called before S3L_thread_comm_setup.

The argument comm specifies an MPI communicator, which should be congruent with, but not identical to, MPI_COMM_WORLD.

A unique communicator must be used for each thread or set of cooperating threads. The term "cooperating threads" refers to a set of threads that will be working on the same data. For example, one thread can initialize a random number generator, obtain a setup ID, and pass this to a fellow cooperating thread, which will then use the random number generator.

In such cases, the user must ensure that the threads within a cooperating set are properly synchronized.

A unique communicator is required because S3L performs internal communications. For example, when S3L_mat_mult is called from a multithreaded program, the thread on one node needs to communicate with the appropriate thread on another node. This can be done only if a communicator that is unique to these threads has been previously defined and passed to the communications routines within S3L.

S3L_thread_comm_setup need not be invoked if S3L functions are called from only one thread in the user's program.

S3L_thread_comm_setup is useful when a user performs explicit multithreading via threads library functions. Since threads library functions are not available in F77, the F77 interface for S3L_thread_comm_setup is not provided.

Syntax

The C and Fortran syntax for S3L_thread_comm_setup are shown below.

C/C++ Syntax

Example 7-53

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_thread_comm_setup(comm)
    MPI_Comm           comm

F77/F90 Syntax

Example 7-54

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_thread_comm_setup(comm, ier)
    integer*4          comm
    integer*4          ier

Input

S3L_thread_comm_setup accepts the following argument as input:

• comm - An MPI communicator that is congruent with, but not identical to, MPI_COMM_WORLD.

Output

S3L_thread_comm_setup uses the following argument for output:

• ier (Fortran only) - When called from a Fortran program, S3L_thread_comm_setup returns error status in ier.

Error Handling

On success, S3L_thread_comm_setup returns S3L_SUCCESS.

S3L_thread_comm_setup performs generic checking of the validity of the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following conditions will cause the function to terminate and return the associated error code:

• S3L_ERR_ARG_NULL - The comm argument is a NULL pointer (C/C++) or 0 (F77/F90)

• S3L_ERR_COMM_INVAL - The comm argument is not congruent to MPI_COMM_WORLD.

• S3L_ERR_THREAD_UNSAFE - The application program is using libraries that are not thread-safe.

Examples

See the following C and Fortran 77 program examples for illustrations of S3L_thread_comm_setup in use:

../examples/s3l/dense_matrix_ops/inner_prod_mt.c
../examples/s3l/dense_matrix_ops/matmult_mt.c

Related Functions

The following may be of related interest.

MPI_Comm_dup(3)
S3L_set_safety(3)
threads(3T)
Also, "Multithreaded Programming" is a relevant section in the Sun MPI
User's Guide