Parallel Process Grids

S3L_set_process_grid

Description

S3L_set_process_grid allows the user to define various aspects of an internal process grid. It returns a process grid handle, which subsequent calls to other Sun S3L functions can use to refer to that process grid.

Syntax

The C and Fortran syntax for S3L_DefineArray are shown below.

C/C++ Syntax

Example 7-11

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_set_process_grid(pgrid,
rank, majorness, grid_extents, plist_length, process_list)
    S3L_pgrid_t        *pgrid
    int                rank
    int                majorness
    int                *grid_extents
    int                plist_length
    int                *process_list

F77/F90 Syntax

Example 7-12

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_set_process_grid(pgrid,
rank, majorness, grid_extents, plist_length, process_list, ier)
    integer*8          pgrid
    integer*4          rank
    integer*4          majorness
    integer*4          grid_extents(*)
    integer*4          plist_length
    integer*4          process_list(*)
    integer*4          ier

Input

S3L_set_process_grid accepts the following arguments as input:

• rank - Specifies the number of dimensions the array will have. The range of legal values for rank is 1 <= rank <= 31.

• majorness - Use one of the following predefined values to specify the order of loop execution:

  • S3L_MAJOR_ROW - Rightmost axis varies fastest.

  • S3L_MAJOR_COLUMN - Leftmost axis varies fastest.

• grid_extents - Integer array whose length equals the rank of the process grid. It contains a list of process grid extents. Each element in the array specifies the extent of the corresponding process grid axis. Note that axis indexing is zero-based for the C/C++ interface and one-based for the F77/F90 interface, as follows:

  • When called from a C or C++ application, the first element of grid_extents corresponds to axis 0, the second element to axis 1, and so forth.

  • When called from an F77 or F90 application, the first element corresponds to axis 1, the second to axis 2, and so forth.

• plist_length - Specifies the length of the process. In C/C++ programs, if the process_list argument is a NULL pointer, plist_length must be 0.

• process_list - Integer array whose length equals the number of processes in the grid. It contains a list of processes. For C/C++ programs, if process_list is a NULL pointer, plist_length must be 0.

Output

S3L_set_process_grid uses the following arguments for output:

• pgrid - The process grid handle returned by the function.

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

Error Handling

On success, S3L_set_process_grid returns S3L_SUCCESS.

S3L_set_process_grid 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_RANK - Invalid rank.

• S3L_ERR_ARG_MAJOR - Invalid majorness.

• S3L_ERR_PGRID_EXTENTS - Grid size (calculated as product of process grid extents) is less than 1.

• S3L_ERR_ARRTOOSMALL - plist_length is greater than 0 but less than the size of the grid (calculated from the product of process grid extents).

• S3L_ERR_ARG_NULL - In a C/C++ program, plist_length is greater than 0 but process_list is a NULL pointer.

Examples

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

Related Functions

S3L_declare_detailed(3)
S3L_free_process_grid(3)

S3L_free_process_grid

Description

S3L_free_process_grid frees the process grid handle returned by a previous call to S3L_set_process_grid.

Syntax

The C and Fortran syntax for S3L_DefineArray are shown below.

C/C++ Syntax

Example 7-13

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_free_process_grid
    S3L_pgrid_t        *pgrid

F77/F90 Syntax

Example 7-14

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_free_process_grid(pgrid, ier)
    integer*8          pgrid
    integer*4          ier

Input

S3L_free_process_grid accepts the following arguments as input:

• pgrid - The process grid handle returned by a previous call to S3L_set_process_grid.

Output

S3L_free_process_grid uses the following arguments for output:

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

Error Handling

On success, S3L_free_process_grid returns S3L_SUCCESS.

On error, the following error code may be returned:

• S3L_PGRID_ERR_NULL - An invalid process grid argument was supplied.

Examples

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

Related Functions

S3L_set_process_grid(3)