HEAPPOOLS (C/C++ and Enterprise PL/I only)

Derivation: HEAP storage POOLS

The HEAPPOOLS runtime option is used to control an optional user heap storage management algorithm, which is known as heap pools. This algorithm is designed to improve the performance of multithreaded applications with a high frequency of calls to malloc(), __malloc31(), calloc(), realloc(), free(), and operators new and delete. When active, heap pools virtually eliminate contention for user heap storage.

HEAPPOOLS runtime option can be used by AMODE 64 applications to manage user heap storage above the 16 M line and below the 2 G bar.

The default value for non-CICS applications is 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).

The default value for CICS® applications is 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).

The default value for AMODE 64 applications is 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).

Read syntax diagramSkip visual syntax diagram
Syntax

                            .-* repeats 11 times---------------------------.      
                            V                                              |      
>>-HEAPPools--(--+-OFF---+----,--+-cell-size---------------+--, percentage-+--)-><
                 +-ON----+       '-(cell-size, pool-count)-'                      
                 '-ALIGN-'                                                        
OFF
Specifies that the heap pools algorithm is not used.
ON
Specifies that the heap pools algorithm is used.
ALIGN
Specifies that Language Environment® will structure 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
Specifies the size of the cells in a heap pool, which is specified as n or nK. The cell size must be a multiple of 8, with a maximum of 65536 (64K).
pool-count
The number of pools to create for the cell size. The pool-count must be in a range from 1 to 255.
percentage
The size of this heap pool and any of its extents is determined by multiplying this percentage by the init_size value that was specified in the HEAP runtime option. The percentage must be in a range from 1 to 90.

Usage notes

  • Cell pool sizes should be specified in ascending order.
  • To use less than twelve 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.
  • Each heap pool is allocated as needed. The allocation of a heap pool can result in the allocation of a heap increment to satisfy the request.
  • The FREE suboption on the HEAP runtime option has no effect on any heap segment 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. To avoid wasting storage, see the heap pool tuning tips specified in z/OS Language Environment Programming Guide.
  • The HEAPPOOLS runtime option has no effect when BELOW is specified as the location on the HEAP runtime option.
  • Mixing of the storage management AWIs (CEEGTST(), CEEFRST() and CEECZST()) and the C/C++ intrinsic functions ( malloc(), calloc(), realloc() and free() ) are 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.
  • Using the ALIGN suboption might cause an increase in the amount of heap storage that is used by an application.
  • You should examine the storage report and adjust storage tuning when first using the ALIGN suboption.
  • The HEAPCHK runtime option does not validate individual heap pool cells.
  • Use of a vendor heap manager (VHM) overrides the use of the HEAPPOOLS runtime option.
  • If the RPTSTG runtime option is specified 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.
  • The HEAPPOOLS runtime option can be used by AMODE 64 applications to manage user heap storage above the 16M line and below the 2G bar.
  • When cell-size is specified without parenthesis, pool-count defaults to 1 rather than being picked up from an earlier setting of pool-count. For example, specifying 128 is treated like specifying (128,1).
  • When cell-size is specified with 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.

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 could 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.
Parent topic: Using the Language Environment runtime options