THREADSTACK

Derivation: THREAD level STACK storage

THREADSTACK controls the allocation of the thread's stack storage for both the upward and downward-growing stacks, except the initial thread in a multithreaded application. If the thread attribute object does not provide an explicit stack size, then the allocation values can be inherited from the STACK option or specified explicitly on the THREADSTACK option.

The default values for non-CICS applications is THREADSTACK(OFF,4K,4K,ANYWHERE,KEEP,128K,128K).

THREADSTACK is ignored under CICS®.

Read syntax diagramSkip visual syntax diagram
Syntax

                   .-OFF-.                          
>>-THREADSTack--(--+-----+--,--+-------------+--,--------------->
                   '-ON--'     '-usinit_size-'      

                       .-ANYWHERE-.     .-KEEP-.      
>--+-------------+--,--+----------+--,--+------+--,------------->
   '-usincr_size-'     +-ANY------+     '-FREE-'      
                       '-BELOW----'                   

>--+-------------+--,--+-------------+--)----------------------><
   '-dsinit_size-'     '-dsincr_size-'      
OFF
Indicates that the allocation suboptions of the STACK runtime option are used for thread stack allocation. Any other suboption specified with THREADSTACK is ignored.
ON
Controls the stack allocation for each thread, except the initial thread, in a multithreaded environment.
usinit_size
Determines the size of the initial upward-growing stack segment. The storage is contiguous. You specify the usinit_size value as n, nK, or nM bytes of storage. The actual amount of allocated storage is rounded up to the nearest multiple of 8 bytes.

The usinit_size value can be preceded by a minus sign. In environments other than CICS, if you specify a negative number Language Environment uses all available storage minus the amount specified for the initial stack segment.

A size of "0" or "-0" requests half of the largest block of contiguous storage in the region below the 16-MB line.

usincr_size
Determines the minimum size of any subsequent increment to the upward-growing stack area. You can specify this value as n, nK, or nM bytes of storage. The actual amount of allocated storage is the larger of two values— usincr_size or the requested size—rounded up to the nearest multiple of 8 bytes

If you specify usincr_size as 0, only the amount of the storage needed at the time of the request, rounded up to the nearest multiple of 8 bytes, is obtained.

The requested size is the amount of storage a routine needs for a stack frame. For example, if the requested size is 9000 bytes, usincr_size is specified as 8K, and the initial stack segment is full, Language Environment gets a 9000 byte stack increment from the operating system to satisfy the request. If the requested size is smaller than 8K, Language Environment gets an 8K stack increment from the operating system.

ANYWHERE | ANY
Specifies that stack storage can be allocated anywhere in storage. On systems that support bimodal addressing, storage can be allocated either above or below the 16M line. If there is no storage available above the line, Language Environment acquires storage below the line. On systems that do not support bimodal addressing (for example, when VM/ESA is initial program loaded in 370 mode) Language Environment ignores this option and places the stack storage below 16M.
BELOW
Specifies that the stack storage must be allocated below the 16M line in storage that is accessible to 24–bit addressing.
KEEP
Specifies that storage allocated to stack increments is not released when the last of the storage in the stack increment is freed.
FREE
Specifies that storage allocated to stack increments is released when the last of the storage in the stack is freed. The initial stack segment is never released until the enclave terminates.
dsinit_size
Determines the size of the initial downward-growing stack segment. The storage is contiguous. You specify the init_size value as n, nK, or nM bytes of storage. The actual amount of allocated storage is rounded up to the nearest multiple of 16 bytes.
dsincr_size
Determines the minimum size of any subsequent increment to the downward-growing stack area. You can specify this value as n, nK, or nM bytes of storage. The actual amount of allocated storage is the larger of two values-- incr_size or the requested size--rounded up to the nearest multiple of 16 bytes.

Usage notes

  • The dsinit_size and dsincr_size values are the amounts of storage that can be used for downward-growing stack frames (plus the stack header, approximately 20 bytes). The actual size of the storage getmained will be 4K (8K if a 4K page alignment cannot be guaranteed) larger to accommodate the guard page.
  • The downward-growing stack is only initialized in a XPLINK supported environment, that is, batch, TSO, z/OS UNIX, and only when a XPLINK application is active in the enclave. Otherwise the suboptions for the downward-growing stack are ignored.
  • All storage allocated to THREADSTACK segments are freed when the thread terminates.
  • The initial stack segment of the thread is never released until the thread terminates, regardless of the KEEP/FREE state.
  • You can specify suboptions with THREADSTACK(OFF,...), but they are ignored. If you override the THREADSTACK(OFF,...) suboption with THREADSTACK(ON) and you omit suboptions, then the suboptions you specified with THREADSTACK(OFF,...) remain in effect. If you respecify THREADSTACK(OFF,...) with different suboptions, they override the defaults.
  • PL/I MTF consideration—THREADSTACK(ON,4K, 4K, BELOW, KEEP,,) provides PL/I compatibility for stack storage allocation and management for each subtask in the application.
  • PL/I considerations—For multitasking or multithreaded environments, the stack size for a subtask or non-Initial Process Thread (non-IPT) is taken from the THREADSTACK option unless THREADSTACK(OFF) is specified. THREADSTACK(OFF) specifies that the values in the STACK option be used.
  • In the multithreaded environment, you can explicitly specify the stack size in the thread attribute object; it will be used instead of the value specified with THREADSTACK or STACK.
  • The THREADSTACK option replaces the NONIPTSTACK and NONONIPTSTACK options.
Parent topic: Using the Language Environment runtime options