11.7　外部库

下面是用于内部子程序例程的Fortran捆绑。

11.7.1　HPF本地例程库

本地HPF过程可使用任意HPF内部或库过程。

对实现者的建议：这种过程的参数将是本地数组。依赖于实现，当从全局HPF代码中调用时，由本地HPF过程所使用的内部及库例程的实际代码可以相同也可不同。（对实现者的建议结束）

另外，提供了本地库过程GLOBAL_ALIGNMENT，GLOBAL__DISTRIBUTION和GLOBAL_TEMPLATE来查询一个外部函数实参的全局映射。所提供的其它本地库例程可查询实参的大小，形状，和数组边界。这些库过程以哑参名作为输入并返回关于相应全局HPF实参的信息。仅能通过本地过程对它们进行引用，这些本地过程可通过全局HPF代码直接引用。如果使用模块机制，则将它们放在名为HPF_LOCAL_LIBRARY的模块中；调用它们的本地例程应包括语句：

　USE HPF_LOCAL_LIBRARY

和一些函数性的适当变种。

本地HPF库通过一个0到n-1的整数标志每个物理处理器，其中n是全局HPF_LIBRARY函数NUMBER_OF_PROCESSORS所返回的值。处理器标志符由ABSTRACT_TO_PHYSICAL所返回，该函数在HPF处理器排列的抽象处理器和物理处理器之间建立了一个一对一的对应关系。另外，本地库函数MY_PROCESSOR返回调用处理器的标志符。

在所有情况下，当要求一个本地HPF库过程参数是一个与全局HPF实参相关联的本地哑参时，这种关联不被认为是过渡的。也就是说，本地哑参必须是一个从全局HPF中而不是从其它本地子程序中引用的过程的哑参。

11.7.1.1　通过块访问哑参

一个全局HPF数组向物理处理器的映射在每个处理器上安放了一个或更多的块，这些块是具有连续索引的元素组。映射到一个处理器的块的数目是映射到它的每一维连续索引块数目的乘积。例如，一个具有CYCLIC(4)分配的一维数组X将拥有包含四个元素的块，除了最后一块可能具有1+SIZE(X)mod4个元素。另一方面，如果X首先与一个模板或一个具有CYCLIC(4)分配的数组对准，且使用一个非单位步长（例如!HPF$ ALIGN X(I) WITH T(3*I)），则它的块可能少于4个元素。在这种情况下，当对准步长是3且模板具有block-cyclic分配（每块4个模板元素），则X每块具有1个或2个元素。如果对准步长为4，则X的所有块正好有1个元素，同时那些没有元素与之对准的模板块不算在块数之内。

HPF_LOCAL子程序中与哑参相关联的全局数组参数的部分可用block-by-block方式访问。LOCAL_BLKCNT，LOCAL_LINDEX和LOCAL_UINDEX这三个本地库例程允许很容易地对特定块的本地存储进行访问。下列例子阐述了这一目的的使用，在该例中，本地数据一次性在一块中初始化。

EXTRINSIC(HPF_LOCAL) SUBROUTINE NEWKI_DONT_HEBLOCK(X)
REAL X(:,:,:)
INTEGER BL(3)
INTEGER, ALLOCATABLE LIND1(:), LIND2(:), LIND3(:)
INTEGER, ALLOCATABLE UIND1(:), UIND2(:), UIND3(:)

BL=LOCAL_BLKCNT(X)

ALLOCATE LIND1(BL(1))
ALLOCATE LIND2(BL(2))
ALLOCATE LIND3(BL(3))

ALLOCATE UIND1(BL(1))
ALLOCATE UIND2(BL(2))
ALLOCATE UIND3(BL(3))

LIND1=LOCAL_LINDEX(X, DIM = 1)
UIND1=LOCAL_UINDEX(X, DIM = 1)

LIND2=LOCAL_LINDEX(X, DIM = 2)
UIND2=LOCAL_UINDEX(X, DIM = 2)

LIND3=LOCAL_LINDEX(X, DIM = 3)
UIND3=LOCAL_UINDEX(X, DIM = 3)

DO IB1=1,BL(1)
　DO IB2=1,BL(2)
　　DO IB3=1,BL(3)
　　　FORALL(I1=LIND1(IB1) : UIND1(IB1), &
　　　　I2=LIND2(IB2) : UIND2(IB2), &
　　　　I3=LIND3(IB3) : UIND3(ib3)) &
　　　　X(I1, I2, I3)=IB1+10*IB2+100*IB3
　　ENDDO
　ENDDO
ENDDO
END SUBROUTINE NEWKI_DONT_HEBLOCK

11.7.1.2　GLOBAL_ALIGNMENT(ARRAY,...)

此过程与HPF查询子程序HPF_ALIGNMENT具有相同的接口和行为，但是它返回的是关于同本地哑参ARRAY相关联的全局HPF数组实参的信息，而不是关于本地数组的信息。

11.7.1.3　GLOBAL_DISTRIBUTION(ARRAY,...)

此过程与HPF查询子程序HPF_DISTRIBUTION具有相同的接口和行为，但是它返回的是关于同本地哑参ARRAY相关联的全局HPF数组实参的信息，而不是关于本地数组的信息。

11.7.1.4　GLOBAL_TEMPLATE(ARRAY,...)

此过程与HPF查询子程序HPF_TEMPLATE具有相同的接口和行为，但是它返回的是关于同本地哑参ARRAY相关联的全局HPF数组实参的信息，而不是关于本地数组的信息。

11.7.1.5　GLOBAL_SHAPE(SOURCE)

描述：返回一个全局HPF实参的形状，该实参与一个数组或一个HPF_LOCAL过程的变量哑参相关联。　

分类：查询函数。

参数：

SOURCE:

可以是任意类型。它可以是一个有值数组或一个标量。它必须是一个HPF_LOCAL过程的哑参，这个参数与一个全局HPF实参相关联。

结果类型，类型参数及形状：结果是一个缺省整数一维数组，该数组的大小等于SOURCE的维数。

结果值：结果值是同关联于SOURCE的实参相关联的全局实参的形状。

例子：假定A由下面的语句定义：

　INTEGER　A(3:100, 200)

且是与B相关联的参数，GLOBAL_SHAPE(B)的值是|98 200|。如果B是同区域A(5:10, 10)相关联的参数，则GLOBAL_SHAPE(B)的值是|6|。

11.7.1.6　GLOBAL_SIZE(ARRAY, DIM)

可选参数：DIM。

描述：返回一个全局HPF实数组参数指定维的范围，该实数组参数与一个HPF_LOCAL的哑数组参数相关联。

分类：查询函数。

参数：

ARRAY：

可以是任意类型。不能是一个标量。它必须是一个HPF_LOCAL过程的哑参，这个参数与一个全局HPF实参相关联。

DIM（可选的）：

必须是一个整型标量，其值的范围是1DIMn，其中n是ARRAY的维数。

结果类型，类型参数及形状：缺省整数标量。

结果值：结果值等于同关联于ARRAY的实参相关联的实参第DIM维的范围，或者如果不存在DIM，则结果值是同关联于ARRAY的实参相关联的实参中元素的总个数。

例子：假定A是由下面的语句定义的：

　INTEGER　A(3:10, 10)

且是与B相关联的参数，GLOBAL_SIZE(B, 1)的值是8。如果B是同区域A(5:10, 2:4)相关联的参数，则GLOBAL_SIZE(B)的值是18。

11.7.1.7　ABSTRACT_TO_PHYSICAL(ARRAY, INDEX, PROC)

描述：返回物理处理器的标志，此物理处理器与一个由全局实数组参数指定的抽象处理器相关联。

分类：子程序。

参数：

ARRAY：

可以是任意类型；必须是一个与全局HPF数组实参相关联的哑参。它是一个INTENT(IN)参数。

INDEX：

必须是一个一维整数数组，该数组包含了全局HPF数组映射到的处理器排列中一个抽象处理器的坐标。它是一个INTENT(IN)参数。INDEX的大小必须等于处理器排列的维数。第i个元素的值必须在1到e_i之间，其中ei是处理器排列第i维的范围。

PROC

必须是一个整型标量。它是一个INTENT(OUT)参数。它接收与INDEX指定抽象处理器相关联的物理处理器的标志值。

11.7.1.8　PHYSICAL_TO_ABSTRACT(ARRAY, PROC, INDEX)

描述：返回一个抽象处理器的坐标，这个抽象处理器与一个全局实参数数组有关，并对应与一个指定的物理处理器。

分类：子程序。

参数：

ARRAY：

ARRAY：

可以是任意类型；必须是一个与全局HPF数组实参相关联的哑参。它是一个INTENT(IN)参数。

PROC

必须是一个整型标量。它是一个INTENT(IN)参数。它包含了一个物理处理器的标志值。

INDEX：

必须是一个一维整数数组。它是一个INTENT(OUT)参数。INDEX的大小必须等于全局HPF数组映射到的处理器排列的维数。INDEX接收与PROC指定的物理处理器相关联的抽象处理器的这个处理器排列内的坐标。第i个元素的值在1到e_i之间，其中ei是处理器排列第i维的范围。

这个过程仅能在抽象处理器和物理处理器之间存在一对一关系的系统上使用。对于这个对应关系是一对多的系统，应该提供一个等价的，依赖于系统的过程。

11.7.1.9　LOCAL_TO_GLOBAL(ARRAY, L_INDEX, G_INDEX)

描述：将本地哑数组内的一组本地坐标转换为相关的全局HPF实参数组内的一组等价的全局坐标。

分类：子程序。

参数：

ARRAY：

可以是任意类型；必须是一个与全局HPF数组实参相关联的哑参。它是一个INTENT(IN)参数

L_INDEX:

必须是一个一维整数数组，其大小等于ARRAY的维数。它是一个INTENT(IN)参数。它包含了本地哑数组ARRAY内一个元素的坐标。第i个元素的值必须在1到e_i之间，其中ei是ARRAY第i维的范围。

G_INDEX:

必须是一个一维整数数组，其大小等于ARRAY的维数。它是一个INTENT(OUT)参数。它接收由L_INDEX标志的本地数组内元素的全局HPF数组实参内的坐标。第i个元素的值在1到e_i之间，其中ei是与ARRAY相关联的全局HPF实参数组的第i维的范围。

11.7.1.10　GLOBAL_TO_LOCAL(ARRAY, G_INDEX, L_INDEX, LOCAL, NCOPIES, PROCS)

可选参数：L_INDEX, LOCAL, NCOPIES, PROCS

描述：将全局HPF实参数组内的一组全局坐标转换为相关的本地哑参数组内的一组等价的本地坐标。

分类：子程序。

参数：

ARRAY:

可以是任意类型；必须是一个与全局HPF数组实参相关联的哑参。它是一个INTENT(IN)参数

G_INDEX:

必须是一个一维整数数组，其大小等于ARRAY的维数。它是一个INTENT(IN)参数。它包含了与本地哑数组ARRAY相关联的全局HPF数组实参内的一个元素的坐标。第i个元素的值必须在1到e_i之间，其中ei是与ARRAY相关联的全局HPF实参数组的第i维的范围。

L_INDEX:

必须是一个一维整数数组，其大小等于ARRAY的维数。它是一个INTENT(OUT)参数。它接收由G_INDEX标志的全局实参数组内元素的本地哑数组内的坐标。（这些坐标在拥有所标志全局数组元素的任意处理器上都是相同的）

第i个元素的值在1到e_i之间，其中ei是ARRAY第i维的范围。

LOCAL（可选的）：

必须是LOGICAL型标量。它是一个INTENT(OUT)参数。如果本地数组包含全局数组元素的一个拷贝，则它被置为.TRUE.，否则为.FALSE.。

NCOPIES(可选的）：

必须是整型标量。它是一个INTENT(OUT)参数。它被置为拥有全局实数组所标志元素拷贝的处理器个数。

PROCS（可选的）：

必须是一维整数数组，其大小至少等于拥有全局实数组所标志元素拷贝的处理器个数。那些处理器的标志数放在PROCS中。它们出现的次序依赖于实现。

11.7.1.11　MY_PROCESSOR()

描述：返回调用物理处理器的标志号。

分类：纯函数。

结果类型，类型参数，和形状：结果是缺省整数标量。

结果值：返回产生调用的物理处理器的标志号。该值的范围是1MY_PROCESSORn-1，其中n是NUMBER_OF_PROCESSORS所返回的值。

11.7.1.12　LOCAL_BLKCNT(ARRAY, DIM, PROC)

可选参数：DIM，PROC

描述：返回每一维中的元素块数，或给定处理器上给定维的元素块数。

分类：纯函数。

参数：

ARRAY：

可以是任意类型；必须是一个与全局HPF数组实参相关联的哑参数组。

DIM（可选的）：

必须是整型标量，其值的范围是1DIMn，其中n是ARRAY的维数。相应的实参不能是可选的哑参。

PROC（可选的）：

必须是整型标量。必须是一个有效的处理器号。

结果类型，类型参数和形状：结果是缺省整型。如果出现DIM，则它是标量；否则结果是一个一维大小为n得数组，其中n是ARRAY的维数。

结果值：

情况(i)：LOCAL_BLKCNT(ARRAY, DIM, PROC)的值是ARRAY根本对准目标第DIM维中与处理器PROC对准的块数且每个块拥有与它们对准的ARRAY的至少一个元素。

情况(ii)：LOCAL_BLKCNT(ARRAY, DIM)返回的值与LOCAL_BLKCNT(ARRAY, DIM, PROC=MY_PROCESSOR())。

情况(iii)：对于i=1, ..., n，LOCAL_BLKCNT(ARRAY)值的第i个部件等于LOCAL_BLKCNT(ARRAY, i)，其中n是ARRAY的维数。

例子：给定定义：

　　　 REAL A( 20 , 20 ) , B( 10 )
!HPF$ 　TEMPLATE T( 100 , 100 )
!HPF$ 　ALIGN B( J ) WITH ( * , J )
!HPF$ 　ALIGN A( I , J ) WITH T( 3* I , 2* J )
!HPF$ 　PROCESSORS PR( 5 , 5 )
!HPF$ 　DISTRIBUTE T( CYCLIC( 3 ) , CYCLIC( 3 ) ) ONTN PR
!HPF$ 　CALL LOCAL_COMPUTE( A , B )
　　　. . .
　　　. . .
　　　. . .
　　　EXTRINSIC( HPF_LOCAL ) SUBROUTINE LOCAL_COMPUTE( X , Y )
　　　USE HPF_LOCAL_LIBRARY
　　　REAL X( : , : ) , Y( : )
　　　INTEGER NBY( 1 ) , NBX ( 2 )
　　　NBX = LOCAL_BLKCNT( X )
　　　NBY = LOCAL_BLKCNT( Y )

对应于PR(2,4)的物理处理器上所返回的NBX中的值是|4 3|，NBY中的值是|1|。

11.7.1.13 LOCAL_LINDEX(ARRAY, DIM, PROC)

可选参数：PROC。

描述：返回一个处理器上给定维中数组哑参所有块的最小本地索引。

分类：纯函数。

参数：

ARRAY：

可以是任意类型；必须是一个与全局HPF数组实参相关联的哑参数组。

DIM：

必须是整型标量，其值的范围是1DIMn，其中n是ARRAY的维数。

PROC（可选的）

必须是整型标量。必须是一个有效的处理器号。

结果类型，类型参数，和形状：结果是一个缺省整型的一维数组，大小为b,其中b是LOCAL_BLKCNT(ARRAY, DIM[, PROC])所返回的值。

结果值：

情况(i)：LOCAL_LINDEX(ARRAY, DIM, PROC)值的第i个部件是处理器PROC上ARRAY第DIM维中第i块第一个元素的本地索引。第i个元素的值在1到e_i之间，其中ei是ARRAY第i维的范围。

情况(ii)：LOCAL_LINDEX(ARRAY, DIM）返回的值与LOCAL_LINDEX(ARRAY, DIM，PROC=MY_PROCESSOR())相同。

例子：用LOCAL_BLKCNT下例子中的相同定义，在对应于PR(2,4)的物理处理器上，由LOCAL_LINDEX(X,DIM=1)所返回的值是|1 2 3 4|；LOCAL_LINDEX(X,DIM=2)的值是|1 3 4|。

11.7.1.13 LOCAL_UINDEX(ARRAY, DIM, PROC)

可选参数：PROC。

描述：返回一个处理器上给定维中数组哑参所有块的最高本地索引。

分类：纯函数。

参数：

ARRAY：

可以是任意类型；必须是一个与全局HPF数组实参相关联的哑参数组。

DIM：

必须是整型标量，其值的范围是1DIMn，其中n是ARRAY的维数。

PROC（可选的）

必须是整型标量。必须是一个有效的处理器号。

结果类型，类型参数，和形状：结果是一个缺省整型的一维数组，大小为b,其中b是LOCAL_BLKCNT(ARRAY, DIM[, PROC])所返回的值。

结果值：

情况(i)：LOCAL_UINDEX(ARRAY, DIM, PROC)值的第i个部件是处理器PROC上ARRAY第DIM维中第i块最后一个元素的本地索引。第i个元素的值在1到e_i之间，其中ei是ARRAY第i维的范围。

情况(ii)：LOCAL_UINDEX(ARRAY, DIM）返回的值与LOCAL_UINDEX(ARRAY, DIM，PROC=MY_PROCESSOR())相同。

例子：用LOCAL_BLKCNT下例子中的相同定义，在对应于PR(2,4)的物理处理器上，由LOCAL_UINDEX(X,DIM=1)所返回的值是|1 2 3 4|；LOCAL_UINDEX(X,DIM=2)的值是|2 3 4|。

11.7.2 从串行外部过程中进行的库访问

一个SERIAL子程序可以包含对于除HPF_ALIGNMENT，HPF_DISTRIBUTION或者HPF_TEMPLATE之外的任意HPF_LIBRARY过程或者HPF内部函数的引用。在一个SERIAL作用域范围之内，不能使用HPF_LOCAL_LIBRARY模块。

引用内部函数NUMBER_OF_PROCESSORS和PROCESSORS_SHAPE所返回的值与这些函数引用出现在全局HPF中相同。

Copyright: NPACT