Derivation: HEAP storage POOLS

The HEAPPOOLS runtime option is used to control an optional heap storage management algorithm known as heap pools. This algorithm is designed to improve performance of multithreaded C/C++ applications with high usage of malloc(), __malloc31(), calloc(), realloc(), free(), new(), and delete(). When active, heap pools can eliminate contention for heap storage.

Non-CICS default

HEAPPOOLS=((OFF,8,10,32,10,128,10,256,10,1024,10,2048, 10,0,10,0,10,0,10,0,10,0,10,0,10),OVR)

CICS® default

HEAPPOOLS=((OFF,8,10,32,10,128,10,256,10,1024,10,2048, 10,0,10,0,10,0,10,0,10,0,10,0,10),OVR)

AMODE 64 default

HEAPPOOLS=((OFF,8,10,32,10,128,10,256,10,1024,10,2048, 10,0,10,0,10,0,10,0,10,0,10,0,10),OVR)

Syntax

                       .-OFF---.      
>>-HEAPPOOLS--=--(--(--+-ON----+--,----------------------------->
                       '-ALIGN-'      

   .-,-------------------------------------------------------.   
   V  (1)                                                    |   
>----------+-cell-size----------------------+--,--percentage-+-->
           '-(--cell-size--,--pool-count--)-'                    

         .-OVR----.      
>--)--,--+-NONOVR-+--)-----------------------------------------><

1. The variable group repeats 11 times

OFF

Specifies that Language Environment® does not use the Heap Pools Manager.

ON

Specifies that Language Environment does use the Heap Pool Manager to manage heap storage requests against the initial heap.

ALIGN

Specifies that Language Environment structures the storage for cells in a heap pool so that a cell less than or equal to 248 bytes does not cross a cache line. For cells larger than 248 bytes, two cells never share a cache line.

cell-size

The size of cells in a heap pool. The cell size must be a multiple of 8 within a range from 8 to 65536. Cell sizes 1K, to 64K are also allowed.

pool-count

The number of pools to be created for the cell size. The pool-count must be in a range from 1 to 255.

percentage

Percentage of the HEAP runtime option init size value to be used as the size for the heap pool and any extents. The percentage must be in a range from 1 to 90.

OVR

Specifies that the option can be overridden.

NONOVR

Specifies that the option cannot be overridden.

Usage notes

• To use less than the supported number of heap pools, specify 0 for the cell size after the last heap pool to be used. For example if four heap pools are desired, use 0 for the fifth cell size when setting the HEAPPOOLS runtime option.
• If the percentage of the HEAP runtime option init size values does not allow for at least one cell, the system automatically adjusts the percentage to enable four cells to be allocated.
• The sum of the percentages may be more or less than 100 percent. This can cause the allocation of a heap pool to require the allocation of a heap increment to satisfy the request.
• Each heap pool is allocated on an as-needed basis. The allocation of a heap pool can result in the allocation of a heap increment to satisfy the request.
• For tuning and performance information, see z/OS Language Environment Programming Guide.
• Heap pools and extents are not released back to the heap, and cell sizes are fixed, so care should be taken when specifying the HEAPPOOLS runtime option to avoid wasting storage.
• The HEAPPOOLS runtime option has no effect when the initial heap is allocated below the 16-MB line. This would be the case when BELOW is specified as the location on the HEAP runtime option.
• The FREE suboption on the HEAP runtime option has no effect on the initial heap or any extents in which a heap pool resides. Each cell in a heap pool can be freed, but the heap pool itself is only released back to the system at enclave termination.
• Mixing of the storage management AWIs (CEEGTST(), CEEFRST() and CEECZST()) and the C/C++ intrinsic functions (malloc(), calloc(), realloc() and free()) is not supported when operating on the same storage address. For example, if you request storage using CEEGTST(), then you may not use free() to release the storage.
• The HEAPPOOLS runtime option applies to the enclave.
• Using the ALIGN suboption might cause an increase in the amount of heap storage used by an application.
• Examine the storage report and adjust storage tuning when first using the ALIGN suboption.
• The RPTSTG runtime option will indicate HEAPPOOLS as one of the runtime options which can be adjusted.
• The HEAPCHK runtime option will indicate that individual cells in the cell pools controlled by the HEAPPOOLS runtime option are not validated. It is the heap pool itself which is validated, as it is the actual storage managed by the regular storage manager.
• If you specify the RPTSTG runtime option while using HEAPPOOLS, extra storage is obtained from the ANYHEAP and is used to complete the storage report on heappools. This extra storage is only allocated when both HEAPPOOLS and RPTSTG are used.
• When cell-size is specified without parenthesis, the default value of pool-count is 1 rather than being picked up from an earlier setting of pool-count. For example, specifying 128 is treated like (128,1).
• When cell-size is specified within parenthesis, pool-count must also be specified.
• When pool-count is greater than 1, the size of each heap pool extent is determined by dividing the heap allocation for the cell-size by the pool-count.
• HEAPPOOLS runtime option can be used by AMODE 64 applications to manage user heap storage above the 16MB line and below the 2GB bar.

Performance considerations

• To improve the effectiveness of the heap pools algorithm, use the storage report numbers generated by the RPTSTG runtime option as an aid in determining optimum cell sizes, percentages, and the initial heap size.
• Use caution when using cells larger than 2K. Large gaps between cell sizes can lead to a considerable amount of storage waste. Properly tuning cell sizes with the help of RPTSTG is necessary to control the amount of virtual storage needed by the application.
• When there are many successful get requests for the same size cell and the maximum elements used in the cell pool is high, this can be an indication that there is excessive contention allocating elements in the cell pool. Specifying pool-count greater than 1 might help relieve some of this contention. Multiple pools are allocated with the same cell size and a portion of the threads are assigned to allocate cells out of each of the pools.