S3L_declare

Description

S3L_declare creates an S3L array handle that describes an S3L parallel array . It supports calling arguments that enable the user to specify

• the array's rank (number of dimensions)

• the extent of each axis

• the array's data type

• which axes, if any, will be distributed locally

• how memory will be allocated for the array

Based on the argument-supplied specifications, a process grid size is internaly determined to distribute the array as evenly as possible.

An array subgrid is the set of array elements that is allocated to a particular process.

The axis_is_local argument specifies which array axes (if any) will be local to the process. It consists of an integer vector whose length is at least equal to the rank (number of dimensions) of the array. Each element of the vector indicates whether the corresponding axis is local or not: 1 = local, 0 = not local.

When axis_is_local is ignored, all array axes except the last will be local. The last axis will be block distributed.

For greater control over array distribution, use S3L_declare_detailed().

Upon successful completion, S3L_declare returns an S3L array handle, which subsequent S3L calls can use as an argument to gain access to that array.

Syntax

The C and Fortran syntax for S3L_declare are shown below.

C/C++ Syntax

Example 7-5

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_declare(A, rank, extents, type, axis_is_local, atype)
    S3L_array_t        *A
    int                rank
    int                *extents
    S3L_data_type      type
    S3L_boolean_t      *axis_is_local
    S3L_alloc_type     atype

F77/F90 Syntax

Example 7-6

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_declare(A, rank, extents, type, axis_is_local, atype, ier)
    integer*8           A
    integer*4          rank
    integer*4          extents(*)
    integer*4          type
    integer*4          axis_is_local(*)
    integer*4          atype
    integer*4          ier

Input

• extents - An integer vector whose length is equal to the number of dimensions in the array. Each element in extents specifies the extent of the corresponding array axis. Note that axis indexing is zero-based for the C interface and one-based for the Fortran interface, as follows:

  • When called from a C or C++ application, the first element of 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.

• type - Specifies the array's data type; this must be a type supported by Sun S3L. See Chapter 4, Sun S3L Data Types for a complete list of supported data types.

• axis_is_local - An integer vector whose length equals the array's rank. Each element of axis_is_local controls the distribution of the corresponding array axis as follows:

  • If axis_is_local[i]= 0, axis[i] of the array will be block-distributed along axis [i] of the process grid.

  • If axis_is_local[i]= 1, axis[i] will not be distributed.

    If axis_is_local is NULL (C/C++) or if its first integer value is negative (F77/F90), this argument will be ignored.

• atype - Use one of the following predefined values to specify how the array will be allocated:

  • S3L_USE_MALLOC - Uses malloc() to allocate the array subgrids.

  • S3L_USE_MEMALIGN64 - Uses memalign() to allocate the array subgrids and to align them on 64-bit boundaries.

  • S3L_USE_MMAP- Uses mmap() to allocate the array subgrids. Array subgrids on the same node will be in shared memory.

  • S3L_USE_SHMGET - Uses shmget() to allocate the array subgrids. Array subgrids on the same node will be in intimate shared memory.

Output

S3L_declare uses the following arguments for output:

• A - S3L_declare returns the array handle in A.

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

Error Handling

On successful completion, S3L_declare returns S3L_SUCCESS.

S3L_declare applies verious checks to the arrays it accepts as arguments. If an array argument fails any of these checks, the function returns an error code indicating the kind of error that was detected and terminates. See Appendix A, S3L Array Checking Errors of this manual for a list of these error codes.

In addition, the following conditions will cause S3L_declare to terminate and return the associated error value:

• S3L_ERR_ARG_RANK - The rank specified is invalid.

• S3L_ERR_ARG_EXTENTS - One or more of the array extents is less than 1.

• S3L_ERR_ARG_BLKSIZE - One or more blocksizes is less than 1.

• S3L_ERR_ARG_DISTTYPE - axis_is_local has one or more invalid values. See the description of axis_is_local in the Input section for details.

Notes

When S3L_USE_MMAP or S3L_USE_SHMGET is used on a 32-bit platform, the part of an S3L array owned by a single SMP cannot exceed 2 gigabytes.

When S3L_USE_MALLOC or S3L_USE_MEMALIGN64 is used, the part of the array owned by any single process can not exceed 2 gigabytes.

If these size restrictions are violated, an S3L_ERR_MEMALLOC will be returned. On 64-bit platforms, the upper bound is equal to the system's maximum available memory.

Examples

../examples/s3l/transpose/ex_trans1.c
../examples/s3l/grade-f/ex_grade.f

Related Functions

S3L_declare_detailed(3)
S3L_free(3)