Heap storage overview

Heap storage is used to allocate storage that has a lifetime not related to the execution of the current routine; it remains allocated until you explicitly free it or until the enclave terminates. You can control allocation and freeing of heap storage using Language Environment callable services, and tune heap storage using the Language Environment runtime options HEAP, THREADHEAP and HEAPPOOLS; see z/OS Language Environment Programming Reference for details.

Heap storage is shared among all program units and all threads in an enclave. Any thread can free heap storage. You can free one element at a time with the CEEFRST callable service, or you can free all heap elements at once using CEEDSHP. You cannot, however, discard the initial heap.

Storage can be allocated or freed with any of the HLL storage facilities, such as malloc(), calloc(), or ALLOCATE, along with the Language Environment storage services. For HLLs with no intrinsic function for storage management, such as COBOL, you can use the Language Environment storage services.

When HEAPPOOLS(ON) or HEAPPOOLS(ALIGN) is in effect, the C storage management intrinsic functions must be used together. That is, if you malloc(), you must use free() to release the storage, you cannot use CEEFRST. See Using HEAPPOOLS to improve performance for more information about heap pools.

Heap storage, sometimes referred to as a heap, is a collection of one or more heap segments comprised of an initial heap segment, which is dynamically allocated at the first request for heap storage, and, as needed, one or more heap increments, allocated as additional storage is required. The initial heap is provided by Language Environment and does not require a call to the CEECRHP service. The initial heap is identified by heap_id=0. It is also known as the user heap. See Figure 1 for an illustration of Language Environment heap storage.

Heap segments, which are contiguous areas of storage obtained directly from the operating system, are subdivided into individual heap elements. Heap elements are obtained by a call to the CEEGTST service, and are allocated within each segment of the initial heap by the Language Environment storage management routines. When the initial heap segment becomes full, Language Environment gets another segment, or increment, from the operating system.

The size of the initial heap segment is governed by the init_size parameter of the HEAP runtime option. (See z/OS Language Environment Programming Reference.) The incr_size parameter governs the size of each heap increment.

A named heap is set up specifically by a call to the CEECRHP service, which returns an identifier when the heap is created. Additional heaps can also be created and controlled by calls to CEECRHP.

Additional heaps provide isolation between logical groups of data in different additional heaps. Separate additional heaps when you need to group storage objects together so they can be freed at once (with a single call to CEEDSHP), rather than freed one element at a time (with calls to CEEFRST).

Library routines occasionally use a heap called the library heap for storage below 16 MB. The size of this heap is controlled by the BELOWHEAP runtime option. The library heap and the BELOWHEAP runtime option have no relation to heaps created by CEECRHP. If an application program creates a heap using CEECRHP, library routines never use that heap (except, of course, the storage management library routines CEEGTST, CEEFRST, CEECZST, and CEEDSHP). The library heap can be tuned with the BELOWHEAP runtime option.

The Language Environment anywhere heap and below heap are reserved for runtime library usage only. Application data and variables are not kept in these heaps. You normally should not adjust the size of these heaps unless the storage report indicates excessive segments allocated for the anywhere or below heaps, or if too much storage has been allocated.

You can use the Language Environment STORAGE option to diagnose the use of uninitialized and freed storage.

You can use the HEAPCHK runtime option to run heap storage tests and to help identify storage leaks. The HEAPZONES runtime option can be used to identify storage overlay damage.

See Using runtime options and z/OS Language Environment Programming Reference for more information about using Language Environment runtime options.

Figure 1 shows the Language Environment heap storage model.