Sun S3L 3.0 Programming and Reference Guide

Performing Miscellaneous S3L Control Functions

This section describes three toolkit functions that support the following tasks:

Enabling thread-safe operation of Sun S3L routines.

Checking the current safety level.

Setting the safety level.

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

Note -

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

`S3L_set_safety`

Description

The S3L safety mechanism offers two types of services:

It performs error checking and reporting during execution of S3L routines.

It synchronizes S3L processes so that, when an error is detected, the section of code associated with the error can be more readily identified.

The S3L safety mechanism can be set to operate at ony one of four levels, which are described in Table 7-2.

Table 7-2 S3L Safety Levels


Safety Level	Description
`0`	Turns the safety mechanism off. Explicit synchronization and errorchecking are not performed. This level is appropriate for productionruns of code that have already been thoroughly tested.
`2`	Detects potential race conditions in multithreaded S3L operations on parallel arrays. To avoid race conditions, an S3L function locks all parallel array handles in its argument list before proceeding. This safety level causes warning messages to be generated if more than one S3L function attempts to use the same parallel array at the same time.
`5`	In addition to checking for and reporting level 2 errors, performsexplicit synchronization before and after each call and locates eacherror with respect to the synchronization points. This safety level isappropriate during program development or during runs for which a small performance penalty can be tolerated.
`9`	Checks for and reports all level 2 and level 5 errors, as well as errorsgenerated by any lower levels of code called from within S3L. Performs explicit synchronization in these lower levels of code and locates each error with respect to the synchronization points. This level is appropriate for detailed debugging following the occurrenceof a problem.

The S3L safety mechanism can be controlled in either of two ways:

By setting the environment variable S3L_SAFETY.

By using the calls S3L_set_safety and S3L_get_safety in a program.

To set the S3L safety level using the S3L_SAFETY environment variable, issue the command:

setenv S3L_SAFETY
{ 0 | 2 | 5 | 9 }

Syntax

The C and Fortran syntax for S3L_set_safety are shown below.

C/C++ Syntax

Example 7-55

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_set_safety(n)
    int                n

F77/F90 Syntax

Example 7-56

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

Input

S3L_set_safety accepts the following argument as input:

n - An integer specifying one of four safety levels: 0, 2, 5, and 9. See the Description section for details.

Output

S3L_set_safety uses the following argument for output:

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

Error Handling

On success, S3L_set_safety returns S3L_SUCCESS.

On error, the following condition will cause the function to return the associated error code and terminate:

S3L_ERR_SAFELEV_INVAL - Safety level has an invalid value.

Examples

../examples/s3l/utils/copy_array.c
../examples/s3l/utils-f/copy_array.f

Related Functions

S3L_get_safety(3)

`S3L_get_safety`

Description

When S3L_get_safety is called from within an application, the value it returns indicates the current setting of the S3L safety mechanism. The possible return values are listed and their meaning explained in Table 7-2.

Syntax

The C and Fortran syntax for S3L_set_safety are shown below.

C/C++ Syntax

Example 7-57

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_get_safety()

F77/F90 Syntax

Example 7-58

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

Input

S3L_get_safety takes no input arguments.

Output

S3L_get_safety returns the S3L safety level. When called by a Fortran program, it uses the following argument for output:

ier - When called from a Fortran program, S3L_get_safety returns error status in ier.

Examples

../examples/s3l/utils/copy_array.c
../examples/s3l/utils-f/copy_array.f

Related Functions

S3L_set_safety(3)