Subject: NUMBER_OF_PROCESSORS . . .

From: David Loveman <[email-masked]>
Date: Fri, 29 May 92 06:40:49 PDT

Proposal for HPF system inquiry intrinsic functions

David Loveman
Digital Equipment Corporation
Version of May 29, 1992

Introduction

In addition to the intrinsic functions of Fortran 90, High Performance
Fortran has two new intrinsic functions:  NUMBER_OF_PROCESSORS and
PROCESSORS_SHAPE.  Their values remain constant for (at least) the
duration of one program execution.  Accordingly, NUMBER_OF_PROCESSORS
and PROCESSORS_SHAPE have values that are restricted expressions and
may be used wherever any other Fortran 90 restricted expression may be
used.  If the system configuration is committed to at compile time,
NUMBER_OF_PROCESSORS and PROCESSORS_SHAPE have values that are constant
expressions and may be used wherever any other Fortran 90 constant
expression may be used.  In particular, NUMBER_OF_PROCESSORS may be
used in a specification expression and, if a constant expression, may
be used in an initialization expression.  None of the categories of
intrinsic functions listed in Chapter 13 of the Fortran 90 standard
seem quite apt to describe the nature of this new intrinsic function,
so we add a new category of "system inquiry functions" and place
NUMBER_OF_PROCESSORS and PROCESSORS_SHAPE in that category.

Note that treating these intrinsics as constant expressions does not
force a compiler to bind the number of processors at compile time
(although that is one possible implementation) -- with the right linker
or code-generation technology the choice could be deferred until run
time, possibly at some performance cost.

Formal Proposal

<this section contains "formal" proposal material, phrased as additions
or modifications to the Fortran 90 specification, with non-proposal
commentary in angle brackets>

<add descriptive section>

13.8a System inquiry functions

In a multi-processor implementation, the processors may be arranged in
an implementation-dependent n-dimensional processor array.  The system
inquiry functions return values related to this underlying machine and
processor configuration, including the size and shape of the underlying
processor array.  NUMBER_OF_PROCESSORS returns the total number of
processors available to the program or the number of processors
available to the program along a specified dimension of the processor
array.  PROCESSORS_SHAPE returns the shape of the processor array.

<add section listing the system inquiry functions>

13.10.21 System inquiry functions

   NUMBER_OF_PROCESSORS(DIM)      Total number of processors in
                                    the processor array.
   PROCESSORS_SHAPE()             Shape of the processor array

<add intrinsic function definitions in the style of Chapter 13 of the
Fortran 90 standard>

13.13.xx  NUMBER_OF_PROCESSORS(DIM)

Optional Argument.  DIM

Description.  Returns the total number of processors available to the
program or the number of processors available to the program along a
specified dimension of the processor array.

Class.  System inquiry function.

Arguments.
DIM (optional)  must be scalar and of type integer with a value in the
range 1<=DIM<=n where n is the rank of the processor array.

Result Type, Type Parameter, and Shape.  Default integer scalar.

Result Value.  The result has a value equal to the extent of dimension
DIM (1<=DIM<=n, where n is the rank of the processor array) of the
processor-dependent hardware processor array or, if DIM is absent, the
total number of elements, equal to or greater than one, of the
processor-dependent hardware processor array.

Examples. For a DECmpp 12000 Model 8B with 8192 processors, the value
of NUMBER_OF_PROCESSORS( ) is 8192, the value of
NUMBER_OF_PROCESSORS(DIM=1) is 128, and the value of
NUMBER_OF_PROCESSORS(DIM=2) is 64.  For a single processor DECalpha
workstation, the value of NUMBER_OF_PROCESSORS( ) is 1, and the value
of NUMBER_OF_PROCESSORS(DIM=1) is 1.

13.13.yy PROCESSORS_SHAPE()

Description.  Returns the shape of the implementation-dependent processor array.

Class.  System inquiry function.

Arguments.  None

Result Type, Type Parameter, and Shape.  The result is a default
integer array of rank one whose size is equal to the rank of the
implementation-dependent processor array.

Result Value.  The value of the result is the shape of the
implementation-dependent processor array.

Example. For a DECmpp 12000 Model 8B with 8192 processors, the value of
PROCESSORS_SHAPE() is (/ 128, 64 /).  For a Connection Machine CM-2
with 8192 processors, the value of PROCESSORS_SHAPE() might be (/ 2, 2,
2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2 /).  For a Connection Machine CM-5 with
8192 processors, the value of PROCESSORS_SHAPE() might be (/ 8192 /). 
For a single processor DECalpha workstation, the value of
PROCESSORS_SHAPE() is (/ 1 /).

<The list of alternatives for Fortran 90 constant expressions and
restricted expression are expanded to include NUMBER_OF_PROCESSORS and
PROCESSORS_SHAPE.>

7.1.6.1 Constant expression

A constant expression is . . . . .

(6a)  A system inquiry function reference where each argument is a
constant expression and the compiler has been informed of the
appropriate system configuration.  

. . . . .

7.1.6.2 Specification expression

A restricted expresion is . . . . .

(9a)  A system inquiry function reference where each argument is a
restricted expression.  

. . . . .

Discussion and Pragmatic Usage - Consequences of the Formal Proposal

The shape of the processor array may be treated as a constant known at
compile time if the compiler is informed about the system
configuration.  This will allow the values of system inquiry functions
to be used in initialization expressions.  The values of system inquiry
functions are always restricted expressions;  thus they may be used in
specification expressions even if the system configuration is not
committed to at compile time.

Note that the system inquiry functions query the physical machine, and
have nothing to do with any PROCESSORS directive that may occur.

References to system inquiry functions may occur in HPF directives.
Example.
!HPF$ TEMPLATE T(100, 3*NUMBER_OF_PROCESSORS())

The definition of NUMBER_OF_PROCESSORS is modeled on the definition of
the SIZE intrinsic function.

The definition of PROCESSOR_SHAPE is modeled on the definition of the
SHAPE intrinsic function.

SIZE(PROCESSOR_SHAPE()) is the rank of the processor array.

As a result of being a constant expression, if the system configuration
is committed to at compile time, suitably constrained references to
system inquiry functions may occur in initialization expressions as,
for example, initialization values in type-declaration-statements or in
parameter-statements.
Examples.
PARAMETER (N_PROCS=NUMBER_OF_PROCESSORS(),        &
           NXPROCS=NUMBER_OF_PROCESSORS(DIM=1),   &
           NYPROCS=NUMBER_OF_PROCESSORS(DIM=2))

As a result of being a restricted expression, suitably constrained
references to system inquiry functions may occur in specification
expressions as, for example, lower or upper bounds of an
explicit-shape-spec of an array-spec in type-declaration-statements.
Examples.
INTEGER, DIMENSION(SIZE(PROCESSOR_SHAPE())) ::   &
           PS = PROCESSOR_SHAPE()
! PS(2) = NUMBER_OF_PROCESSORS(DIM=2)

Earlier proposals for this type of facility used a form of predefined
named constant, N$PROCS.  This form is rejected for several reasons:
1.  Nowhere else in Fortran is there such a thing as a predefined named constant.
2.  "$" is a legal Fortran character, but not as a character in a name.
3.  If ones implementation supports "$" as a legal character in names,
one could always define 
PARAMETER (N$PROC = NUMBER_OF_PROCESSORS())
4.  Use of a long name for an intrinsic is a strong encouragement for
subset implementations to support 31 character names in general.

---

From: Guy Steele <[email-masked]>
Date: Mon, 1 Jun 92 12:21:50 EDT

This version of the proposal looks great to me, and seems to
fit in with the style of the Fortran 90 standard.

My one suggestion is that computers that are unreservedly committed
to being single processors might be regarded as having a scalar processor
arrangement, and we might want to have an example reflecting that:

 For a BananaKlone 2000 laptop, which has a single processor,
 the value of NUMBER_OF_PROCESSORS( ) is 1, and there is
 no valid value of DIM for which NUMBER_OF_PROCESSORS may be called.

 For a BananaKlone 2000 laptop, which has a single processor,
 the value of PROCESSORS_SHAPE() is [] (that is, an empty rank-one array).

--Guy