Create Activation Group-Based Heap Space (CRTHS)


Op Code (Hex) Operand 1 Operand 2

03B2 Heap identifier Creation template

Operand 1: Binary(4) variable scalar.

Operand 2: Space pointer.

Bound program access
Built-in number for CRTHS is 112.
CRTHS (
       heap_identifier     : address of signed binary(4) OR
                             address of unsigned binary(4)
       creation_template   : address
)

Note: The term "heap space" in this instruction refers to an "activation group-based heap space".

Description

A heap space is created with the attributes supplied in the heap space creation template specified by operand 2. The heap space identifier used to perform allocations and marks against the heap space is returned in operand 1.

The heap identifier returned in operand 1 represents the heap space. This identifier is used for the Allocate Activation Group-Based Heap Space Storage (ALCHSS), Destroy Activation Group-Based Heap Space (DESHS), Set Activation Group-Based Heap Space Storage Mark (SETHSSMK) and Materialize Activation Group-Based Heap Space Attributes (MATHSAT) instructions.

The heap space creation template identified by operand 2 must be 16-byte aligned in the space. Operand 2 is not modified by the instruction.

The following is the format of the heap space creation template:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Reserved (binary 0)
Char(8)
8 8
Maximum single allocation
UBin(4)
12 C
Minimum boundary alignment
UBin(4)
16 10
Creation size
UBin(4)
20 14
Extension size
UBin(4)
24 18
Domain/Storage protection
Bin(2)



Hex 0000 = System should chose the domain
Hex 0001 = The heap space domain should be "User"
Hex 8000 = The heap space domain should be "System"


26 1A
Heap space creation options
Char(6)
26 1A
Allocation strategy
Bit 0



0 = Normal allocation strategy
1 = Force process space creation on each allocate


26 1A
Heap space mark
Bit 1



0 = Allow heap space mark
1 = Prevent heap space mark


26 1A
Block transfer
Bit 2



0 = Transfer the minimum storage transfer size for this object
1 = Transfer the machine default storage transfer size for this object


26 1A
Process access group member
Bit 3



0 = Do not create the heap space in the PAG
1 = Create the heap space in the PAG


26 1A
Allocation initialization
Bit 4



0 = Do not initialize allocations
1 = Initialize allocations


26 1A
Overwrite freed allocations
Bit 5



0 = Do not overwrite freed allocations
1 = Overwrite freed allocations


26 1A
Reserved (binary 0)
Bits 6-7
27 1B
Allocation value
Char(1)
28 1C
Freed value
Char(1)
29 1D
Reserved (binary 0)
Char(3)
32 20
Reserved (binary 0)
Char(64)
96 60
--- End ---

The maximum single allocation of any single allocation from the heap space is useful for controlling the use of the heap space and may also improve performance for some cases when the machine can optimize access based on this attribute. The minimum value that can be specified is 0 bytes, and the maximum value that can be specified is (16M - 1 page) bytes. To determine the current page size use the MATRMD instruction. If zero is specified, the default value of (16M - 1 page) bytes is used. Values outside the range indicated will cause a template value invalid  (hex 3801) exception.

The minimum boundary alignment associated with any allocation from the heap space can be specified in the template as an advisory value. This value is expressed in terms of byte alignment. The machine will use the specified value to choose an actual alignment which is deemed closest to a machine-required alignment value. This allows changing machine requirements to be met without changing the advisory value. Storing valid pointers in heap space allocations will be supported for all advisory values, so the smallest effective alignment value is 16 byte alignment.

The creation size of the heap space can be specified in the template. If zero is specified, the system computes a default value. The minimum value that can be specified is 1 page (in bytes). The maximum value that can be specified is (16M - 1 page) bytes. To determine the current page size use the MATRMD instruction. The value specified is rounded up to a storage unit boundary. Values outside the range indicated cause a template value invalid  (hex 3801) exception. This is an advisory value only. The machine may decide to override the value specified based on system resource constraints.

The extension size of the heap space can be specified in the template. If zero is specified, the system computes a default value. The minimum value that can be specified is 1 page (in bytes). The maximum value that can be specified is (16M - 1 page) bytes. To determine the current page size use the MATRMD instruction. The value specified is rounded up to a storage unit boundary. Values outside the range indicated cause a template value invalid  (hex 3801) exception. This is an advisory value only. The machine may decide to override the value specified based on system resource constraints.

The domain/storage protection field in the template allows the user of this instruction to override the domain for the heap space that would otherwise be chosen by the machine. The domain/storage protection attribute can be used to restrict access to the contents of the heap space by user state programs. It is possible to limit the access of the heap space by user state programs into 1 of two levels:

Only a system state program can specify a heap space to be created with a domain of system. If a user state program attempts to specify the domain/storage protection as system, a template value invalid  (hex 3801) exception will be signaled. Any value other than the ones listed will cause a template value invalid  (hex 3801) exception to be signaled.

The normal allocation strategy as defined by the machine will be used unless the force process space creation on each allocation attribute is indicated. This option should only be used in unusual situations, such as when necessary for debug of application problems caused by references outside an allocation.

The heap space mark attribute can be used to prevent the use of the Set Activation Group-Based Heap Space Storage Mark (SETHSSMK) and Free Activation Group-Based Heap Space Storage from Mark(FREHSSMK) instructions on a heap space.

Block transfer on a heap space is used to increase the performance of a heap space based on prior knowledge of the program creating the heap space on how that heap space will be used. This attribute is used only when the heap space is not a member of a process access group (PAG).

A heap space can be created as a process access group (PAG) member of the process associated with the current thread, if specified by the process access group member field. It is possible for the PAG to overflow at which point any requested heap space creations or extensions will not reside in the PAG. Thus the specification to have the heap space as a member of the PAG is only an advisory which the machine may decide to override.

The allocation initialization field in the template allows the user of this instruction to specify that all storage allocations from the heap space being created will be initialized to the allocation value supplied in the template. If the user chooses not to initialize heap space storage allocations, the initial value of heap space storage allocations is unpredictable but will not expose data produced by a different user profile.

The overwrite freed allocations field in the template allows the user of this instruction to specify that all heap space storage allocations upon being freed will be overwritten with the freed value supplied in the template. If the user chooses not to overwrite heap space storage allocations when freed, the contents of the freed allocations will be unaltered.

A default heap space (heap identifier value of 0) is automatically available in each activation group, without issuing a Create Activation Group-Based Heap Space (CRTHS) instruction. The default heap space is created on the first allocation request of the default heap space. See Allocate Activation Group-Based Heap Space Storage (ALCHSS) for a description of the default heap space.

A heap space is scoped to an activation group, thus the maximum life of a heap space is the life of the activation group in which the heap space was created. A heap space can only be destroyed from within the activation group in which it was created.

Limitations (Subject to Change)

The following are limits that apply to the functions performed by this instruction.

The amount of heap space storage that can be allocated for a single heap space is 4G-512K bytes. Due to fragmentation a heap space may grow to 4GB-512KB without having 4GB-512KB of outstanding heap space storage allocations.

Authorization Required

Lock Enforcement

Exceptions

06 Addressing

08 Argument/Parameter

10 Damage Encountered

1C Machine-Dependent

20 Machine Support

24 Pointer Specification

38 Template Specification

44 Protection Violation