CM FORTRAN LIBRARIES REFERENCE MANUAL Version 2.1, January 1994 Copyright (c) 1994 Thinking Machines Corporation. CHAPTER 4: DYNAMIC ALLOCATION ****************************** Three subroutines allocate CM arrays at run time, giving the programmer different levels of control over the array's layout. A fourth subroutine deallocates an array created by any of the other three. CALL CMF_ALLOCATE_ARRAY & ( FE_ARRAY, EXTENTS, RANK, TYPE ) CALL CMF_ALLOCATE_LAYOUT_ARRAY & ( FE_ARRAY, EXTENTS, RANK, TYPE, ORDERS, WEIGHTS ) CALL CMF_ALLOCATE_DETAILED_ARRAY & ( FE_ARRAY, EXTENTS, RANK, TYPE, ORDERS, & SUBGRIDS, PMASKS ) CALL CMF_DEALLOCATE_ARRAY( FE_ARRAY ) The FE_ARRAY argument is an integer front-end vector whose length is the pre-defined constant CMF_SIZEOF_DESCRIPTOR. This array is treated as the descriptor of a CM array; the remaining arguments specify information to be placed in the slots of the descriptor. All three variants take as arguments: o EXTENTS a front-end vector that contains dimension extents o RANK a scalar integer that indicates rank o TYPE a pre-defined integer constant that indicates type: CMF_LOGICAL CMF_S_INTEGER, CMF_LONG_S_INTEGER CMF_FLOAT, CMF_DOUBLE, CMF_COMPLEX, CMF_DOUBLE_COMPLEX The FE_ARRAY argument cannot be used as a CM array within the program unit that calls the allocation subroutine, since that program unit treats it as a front-end array. Instead, you pass the FE_ARRAY argument (that is, the descriptor) to another program unit that explicitly declares it a CM array. This method is illustrated in the following example. 4.1 ALLOCATION EXAMPLE (CANONICAL LAYOUT) ------------------------------------------ ---------------------------------------------------------------------- SUBROUTINE ALLOCATE() IMPLICIT NONE INTEGER NEW_ARRAY(CMF_SIZEOF_DESCRIPTOR) INTEGER EXTENTS(7), RANK, I PARAMETER (RANK=3) INCLUDE '/usr/include/cm/CMF_defs.h' DO I=1,RANK EXTENTS(I) = I * 10 END DO CALL CMF_ALLOCATE_ARRAY & (NEW_ARRAY, EXTENTS, RANK, CMF_S_INTEGER) CALL PRINT_DIMS3D(NEW_ARRAY) CALL CMF_DEALLOCATE_ARRAY(NEW_ARRAY) END SUBROUTINE ALLOCATE SUBROUTINE PRINT_DIMS3D(IN) IMPLICIT NONE INTEGER IN(:,:,:) PRINT *,"Shape of DUMMY is (",DUBOUND(IN,1), & ",",DUBOUND(IN,2), & ",",DUBOUND(IN,3),")" END SUBROUTINE PRINT_DIMS3D ---------------------------------------------------------------------- 4.2 CONTROLLING ARRAY LAYOUT ----------------------------- The "layout" and "detailed" variants of the allocation procedures take additional front-end vector arguments that contain layout information for each of the array dimensions. The significance of these arguments is comparable to the various forms of the cmf compiler directive LAYOUT. o ORDERS contains symbolic constants indicating the ordering of each dimension: CMF_SERIAL_ORDER, CMF_NEWS_ORDER, or (for CM- 2/200 systems) CMF_SEND_ORDER. o WEIGHTS is a vector of integers indicating relative dimension weights. o SUBGRIDS is a vector of integers indicating the desired subgrid length for each dimension (comparable to the :BLOCK item in the detailed-layout directive). o PMASKS is a vector of integers that serve as bit-masks to indicate the desired processors (comparable to the :PDESC item in the detailed-layout directive). If ORDERS contains the value CMF_SERIAL_ORDER for any dimension, then PMASKS must contain 0 for that dimension. There is no form directly comparable to the :BLOCK :PROCS form of the detailed LAYOUT directive. However, if PMASKS contains all zeros, the system computes the number of processors for each axis as extent / subgrid-length, rounded if necessary to the next power of 2. 4.3 ALLOCATION EXAMPLE (DETAILED LAYOUT) ----------------------------------------- ---------------------------------------------------------------------- IMPLICIT NONE INCLUDE '/usr/include/cm/CMF_defs.h' INTEGER NEWARRAY(CMF_SIZEOF_DESCRIPTOR) INTEGER EXTENTS(7),ORDERS(7),SUBGRIDS(7),PMASKS(7) INTEGER RANK,I INTEGER NPN,NPN_FRAC,FRAC,SG1,SG2 REAL A(200) PARAMETER (RANK = 2) PARAMETER (FRAC = 4) PARAMETER (SG1 = 5, SG2 = 40) A = 1.0 ! initialize if CM-2 in auto-attach mode NPN = CMF_NUMBER_OF_PROCESSORS() NPN_FRAC = NPN/FRAC PMASKS(1) = (NPN_FRAC - 1) * FRAC PMASKS(2) = FRAC - 1 SUBGRIDS(1) = SG1 SUBGRIDS(2) = SG2 EXTENTS(1) = NPN_FRAC * SG1 EXTENTS(2) = FRAC * SG2 DO I = 1,RANK ORDERS(I) = CMF_NEWS_ORDER END DO CALL CMF_ALLOCATE_DETAILED_ARRAY & (NEWARRAY,EXTENTS,RANK,CMF_FLOAT,ORDERS, & SUBGRIDS,PMASKS) CALL USE_NEWARRAY(NEWARRAY,EXTENTS) CALL CMF_DEALLOCATE_ARRAY(NEWARRAY) END SUBROUTINE USE_NEWARRAY(A,EXT) INTEGER EXT(2) REAL A(EXT(1),EXT(2)), B(EXT(1),EXT(2)) CMF$ LAYOUT A(:,:) CMF$ ALIGN B(I,J) WITH A(I,J) B = CSHIFT(A,DIM=1,SHIFT=1) C Other operations on arrays A and B RETURN END ---------------------------------------------------------------------- 4.4 RESTRICTION ---------------- In addition to the general restrictions listed in Section 1.4, the following restriction applies only to the dynamic allocation utilities. o All four dynamic allocation utilities are incompatible with run- time safety, including argument checking and NaN checking. Do not use -safety to compile a program that uses these procedures. 4.5 LANGUAGE COMPARISON ------------------------ The dynamic allocation utility procedures are largely, but not completely, redundant with the CM Fortran statement ALLOCATE, which creates deferred-shape CM arrays. Some differences are: o ALLOCATABLE arrays cannot appear in COMMON, so their names are not available to all program units. Array pointers and arrays created with CMF_ALLOCATE_ARRAY or one of its variants can be globally available. o Data types and ranks of deferred-shape arrays must be known at compile time. With CMF_ALLOCATE_ARRAY, they can be decided at run time (although used only in subroutines where the appropriate type and rank are declared). o Storage allocated for deferred-shape arrays is deallocated upon exit from the program unit. Storage allocated by a utility subroutine must be deallocated explicitly by a call to CMF_DEALLOCATE_ARRAY. o If a deferred-shape array is subject to a LAYOUT directive, the directive must appear in the specification part of the program unit (before any executable code), and the values of any variables used in the directive are those established upon entry. If you use the utility CMF_ALLOCATE_LAYOUT_ARRAY or CMF_ALLOCATE_DETAILED_ARRAY instead, you can compute before the call to determine layout-related values, such as subgrid lengths. The variable values used are those established at the time of execution. o The dynamic allocation utilities are incompatible with run-time safety, but deferred-shape arrays can be used in programs compiled with -safety. Neither the Utility Library nor the CM Fortran language provides for dynamic allocation of front-end arrays or scalars. For this purpose, use the CM Fortran subroutines FMALLOC and FFREE in libcmf77.a (described in Part III). These subroutines provide an interface to the standard malloc and free functionality that, together with the %VAL operator, enable you to manage front-end storage. Man Pages --------- To view UNIX-style man pages for CM array allocation subroutines, on a CM-5 type man on a CM-2 type cmman or from within commands-only Prism type m where is one of CMF_ALLOCATE_ARRAY CMF_ALLOCATE_LAYOUT_ARRAY CMF_ALLOCATE_DETAILED_ARRAY CMF_DEALLOCATE_ARRAY ***************************************************************** The information in this document is subject to change without notice and should not be construed as a commitment by Think- ing Machines Corporation. Thinking Machines reserves the right to make changes to any product described herein. Although the information in this document has been reviewed and is believed to be reliable, Thinking Machines Corporation assumes no liability for errors in this document. Thinking Machines does not assume any liability arising from the application or use of any information or product described herein. ***************************************************************** Connection Machine (r) is a registered trademark of Thinking Machines Corporation. CM, CM-2, CM-200, CM-5, CM-5 Scale 3, and DataVault are trademarks of Thinking Machines Corporation. CMOST, CMAX, and Prism are trademarks of Thinking Machines Corporation. C* (r) is a registered trademark of Thinking Machines Corporation. Paris and CM Fortran are trademarks of Thinking Machines Corporation. CMMD, CMSSL, and CMX11 are trademarks of Thinking Machines Corporation. CMview is a trademark of Thinking Machines Corporation. Scalable Computing (SC) is a trademark of Thinking Machines Corporation. Scalable Disk Array (SDA) is a trademark of Thinking Machines Corporation. Thinking Machines (r) is a registered trademark of Thinking Machines Corporation. SPARC and SPARCstation are trademarks of SPARC International, Inc. Sun, Sun-4, and Sun Workstation are trademarks of Sun Microsystems, Inc. UNIX is a trademark of UNIX System Laboratories, Inc. Copyright (c) 1994 by Thinking Machines Corporation. All rights reserved. This file contains documentation produced by Thinking Machines Corporation. Unauthorized duplication of this documentation is prohibited. Thinking Machines Corporation 245 First Street Cambridge, Massachusetts 02142-1264 (617) 234-1000