S3L_forall

Description

S3L_forall applies a user-defined function to elements of a parallel Sun S3L array. and sets its values accordingly. Three different function types are supported. These types are described in Table 7-1.

Here, <type> is one of: integer*4, integer*8, real*4, real*8, complex*8, or complex*16 and rank is the rank of the array.

For S3L_ELEM_FN1, the user function is applied to each element in the array.

For S3L_ELEM_FNN, the user function is supplied the local subgrid address and subgrid size and iterates over subgrid elements. This form delivers the highest performance because the looping over the elements is contained within the function call.

For S3L_INDEX_FN, the user function is applied to each element in the subarray specified by the triplets argument to S3L_forall. If the triplets argument is NULL in C/C++ or has a leading value of 0 in F77/F90, the whole array is implied. The user function may involve the global coordinates of the array element; these are contained in the coord argument. Global coordinates of array elements are 0-based for C programs and 1-based for Fortran programs.

When a Fortran program uses triplets, the length of first axis of the triplets must equal the rank of the array. Failure to meet this requirement can produce wrong results or a segmentation violation.

A subgrid is the portion of the parallel array that is owned by a process. A subarray is the portion of the parallel array that is described by a lower bound, an upper bound, and a stride in each dimension.

Syntax

The C and Fortran syntax for S3L_cshift are shown below.

C/C++ Syntax

Example 7-27

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_forall(a, user_fn, fn_type, triplets)
    S3L_array_t        a
    void               (*user_fn)()
    int                fn_type
    int                triplets[rank][3]

where rank is the rank of the array.

F77/F90 Syntax

Example 7-28

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_forall(a, user_fn, fn_type, triplets, ier)
    integer*8          a
    <external>         user_fn
    integer*4          fn_type
    integer*4          triplets(rank,3)
    integer*4          ier

where rank is the rank of the array.

Input

S3L_forall accepts the following arguments as input:

• a - Parallel array to which the function will be applied.

• user_fn - Pointer to the user-defined function.

• fn_type - Predefined value specifying the class of functions to which the function belongs. See the Description section for a list of valid fn_type entries.

• triplets - An integer vector that is used to restrict the function to a range of elements. A triplet takes the form:

inclusive lower bound inclusive upper bound stride

for each axis of the array. The stride must be positive. To apply the function to all the elements in the array, set triplets to NULL (C/C++) or to 0 (F77/F90).

Output

S3L_forall uses the following argument for output:

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

Error Handling

On success, S3L_forall returns S3L_SUCCESS.

S3L_forall 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 condition will cause the function to terminate and return the associated error code:

• S3L_ERR_FORALL_INVFN - User-specified function is invalid. fn_type is not one of:

  • S3L_ELEM_FN1

  • S3L_ELEM_FNN

  • S3L_INDEX_FN

• S3L_ERR_INDX_INVALID - fn_type is S3L_INDEX_FN and one or more of the elements in the triplets argument has an invalid value.

Examples

../examples/s3l/forall/ex_forall.c
../examples/s3l/forall/ex_forall2.cc
../examples/s3l/forall-f/ex_forall.f