HEAPPOOLS64 (C/C++ and AMODE 64 only)

Derivative: HEAP storage POOLS for AMODE 64

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

The default value for AMODE64 applications is HEAPPOOLS64(OFF,8,4000,32,2000,128,700,256,350, 1024,100,2048,50,3072,50,4096,50,8192,25,16384,10,32768,5,65536,5).

Read syntax diagramSkip visual syntax diagram HEAPPOOLS64HP64 (OFFONALIGN* repeats 11 times,cell-size(cell-size, pool-count), count)
Specifies that the heappools algorithm is not being used.

The default is OFF.

Specifies that the heappools algorithm is being used.
Specifies that Language Environment® will structure the storage for cells in a heap pool so that a cell less than or equal to 240 bytes does not cross a cache line. For cells larger than 240 bytes, two cells never share a cache line.
Specifies the size of the cells in a heap pool, specified as n or nK. The cell size must be a multiple of 8, with a maximum of 65536 (64K).
The number of pools to create for the cell size. The pool-count must be in a range from 1 to 255.
Specifies the number of cells of the corresponding size to be allocated initially. The minimum cell count is 4.

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 HEAPPOOLS64 runtime option.
  • 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.
  • 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 HEAPCHK runtime option does not validate individual heap pool cells.
  • If you specify the RPTSTG runtime option while using HEAPPOOLS64, extra storage is obtained from the LIBHEAP64 and is used to complete the storage report on heappools. This extra storage is only allocated when both HEAPPOOLS64 and RPTSTG are used.
  • 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 that are generated by the RPTSTG runtime option as an aid in determining optimum cell sizes and count.
  • 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 that is needed by the application.

For more information

For more information about heap storage and heap storage tuning with storage report numbers, see Heap storage overview and Tuning heap storage in z/OS Language Environment Programming Guide.