6.4. Memory Management

FMS contains a memory management system that you can use for scratch data storage. When FMSINI is called, a pool of memory is created. FMS allocates memory from this pool as required.

The size of the memory pool is determined by the FMS parameter MAXMD. FMS keeps track of the memory used out of the pool with the Parameter MDUSED. At any point you may determine how much memory is left in the pool as follows:

        CALL FMSIGT('MAXMD', MAXMD)
        CALL FMSIGT('MDUSED', MDUSED)
        MDLEFT = MAXMD - MDUSED

You may allocate memory from this pool for scratch data storage. This has the following advantages for your application:

Less Programming Errors
Dynamically allocating storage that is the exact size produces less programming errors than arrays having fixed dimensions. As the problem size changes, the storage automatically changes also. If the code works on a small problem, it will also work on a large one. By contrast, fixed dimension arrays provide no warning when they are exceeded, resulting in programming errors that are hard to trace.
Portability
All FMS subroutines have the same application program interface on all platforms. This means that you do not need to change your application as you move between platforms. FMS handles the details of implementing memory management correctly on each platform.
More Efficient Code
By allowing arrays to adjust dynamically, your data for each problem will be packed into just the right amount of memory. This makes better use of the cache than data that is more distributed.
Shared Memory
The memory in the FMS memory pool is automatically shared among all processors. If you are using the FMS parallel processing utilities to run your code in parallel, the shared problem data must be in the FMS memory pool.

The first step in using memory in the FMS memory pool is to declare an array in your program that you will use to reference the allocated memory. There are currently two mechanisms used to do this.

Machines supporting FORTRAN pointers
If your machine supports the FORTRAN POINTER statement, the reference arrays are obtained by including the POINTER statements for the arrays and obtaining the pointer values by calling FMSIGT, as follows:

        POINTER (CMD_PTR, CMD)
        POINTER (RMD_PTR, RMD)
        POINTER (IMD_PTR, IMD)
        COMPLEX*16 CMD(0:1)
        REAL*8     RMD(0:1)
        INTEGER    IMD(0:1)
	  ...
        CALL FMSIGT ('MEMPTR',CMD_PTR)
        CALL FMSRGT ('MEMPTR',RMD_PTR)
        CALL FMSCGT ('MEMPTR',IMD_PTR)

Machines not supporting FORTRAN pointers
If your machine does not support the FORTRAN POINTER statement, the reference arrays are obtained as follows:
```
        COMMON CMD
        EQUIVALENCE (IMD, RMD, CMD)
        COMPLEX*16 CMD(0:1)
        REAL*8     RMD(0:1)
        INTEGER    IMD(0:1)
```
On most machines, FMS automatically aligns BLANK COMMON on a 16-byte boundary.
You should not be concerned if you use BLANK COMMON for other purposes. FMS does not store any data in CMD(0:1). It simply uses the arrays IMD, RMD and CMD as reference points for the allocated memory.

Once the reference arrays are established in your subroutine, you call FMSIMG to allocate LEN integer words starting at IMD(LOC), FMSRMG to allocate LEN REAL*8 words starting at RMD(LOC), or FMSCMG to allocate LEN COMPLEX*16 words starting at CMD(LOC).

The value of LOC returned is relative to the array value you provide on the call. For example, if you make the call:

        CALL FMSIMG (IMD(10), LOC, LEN)

the allocated memory will start at IMD(10+LOC).

You may make the value of LOC be an actual subscript of the array by dimensioning the array to start at 0,

	INTEGER IMD (0:1)

Then when you call the memory allocation subroutine

	CALL FMSIMG (IMD, LOC, LEN)

the allocated memory will start at IMD(LOC).

When you no longer require the storage, you can return it to the pool by calling

        CALL FMSIMR(IMD,LOC,LEN)
        CALL FMSRMR(RMD,LOC,LEN)
        CALL FMSCMR(CMD,LOC,LEN)

If you want to list the contents of the FMS memory pool, you can include the statement

        CALL FMSCST('SHOW','MEMORY')

You should return the memory you allocated to the memory pool before calling the FMS matrix algebra subroutines. This will prevent memory from being idle during FMS processing.

If you use the FMS parallel processing utilities to run part of your application in parallel, you may also call the FMS memory management routines from within your application. Each process will allocate a private region from the memory pool. For example, if you have 8 processes running and each calls the FMS memory management routines to allocate a region of memory, a total of 8 regions will be allocated.