set_thread_limits (BPX1STL, BPX4STL) — Change task or thread limits for pthread_created threads

Function

The set_thread_limits callable service changes the calling process's limits for pthread_created threads. These limits are the maximum number of MVS tasks used for pthread_created threads, and the maximum number of pthread_created threads. The thread limit includes running, queued, and undetached exited threads.

Requirements

Operation Environment
Authorization: Supervisor state or problem state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX1STL): 31-bit
AMODE (BPX4STL): 64-bit
ASC mode: Primary mode
Interrupt status: Enabled for interrupts
Locks: Unlocked
Control parameters: All parameters must be addressable by the caller and in the primary address space.

Format

The syntax format is as follows:
CALL BPX1STL,(Action,
              MaxThreadTasks,
              MaxThreads,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4STL with the same parameters.

Parameters

Action
Supplied parameter
Type:
Integer
Length:
Fullword
The name of a fullword that contains a numeric value that identifies the process's pthread_created thread limits that are to be set. The following constants, which are defined in BPXYCONS, define the actions that are to be taken (see BPXYCONS — Constants used by services):
STL_MAX_TASKS
Replace the MaxThreadTasks limit for the caller's process with the value that is specified in MaxThreadTasks only.
STL_MAX_THREADS
Replace the MaxThreads limit for pthread_created threads in the caller's process with the fullword value that is specified in MaxThreads only.
STL_SET_BOTH
Replace both the MaxThreadTasks and MaxThreads limits for the caller's process with the fullword values that are specified in MaxThreadTasks and MaxThreads, respectively.
MaxThreadTasks
Supplied parameter
Type:
Integer
Length:
Fullword

When the Action that is specified is STL_MAX_TASKS or STL_SET_BOTH, this is the name of a fullword that contains the new MaxThreadTasks value for the caller's process.

MaxThreads
Supplied parameter
Type:
Integer
Length:
Fullword

When the Action that is specified is STL_MAX_THREADS or STL_SET_BOTH, this is the name of a fullword that contains the new MaxThreads value for the caller's process.

Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the set_thread_limits service returns 0 if the request is successful, or -1 if it is not successful.

Return_code
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the set_thread_limits service stores the return code. The set_thread_limits service returns Return_code only if Return_value is -1. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes The set_thread_limits service can return one of the following values in the Return_code parameter:
Return_code Explanation
EINVAL The value that was specified for Action, MaxThreadTasks, or MaxThreads is incorrect. The following reason codes can accompany the return code: JRSTLActionInvalid, JRSTLTasksInvalid or JRSTLThreadsInvalid.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the set_thread_limits service stores the reason code. The set_thread_limits service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.

Usage notes

  1. If the set_thread_limits service returns with an unsuccessful return value (-1), the original MaxThreadTasks and MaxThreads values for the caller's process remain unchanged.
  2. If any caller, authorized or nonauthorized, attempts to set a limit outside the allowable ranges (see Table 2), the set_thread_limits service returns with a return code of EINVAL and a reason code of JRSTLTasksInvalid or JRSTLThreadsInvalid. Parmlib represents the values that are specified at z/OS UNIX startup by the BPXPRMxx parmlib member.
    • For MaxThreadTasks, the limits are shown in Table 1.
      Table 1. Allowable thread limits for MaxThreadTasks
      Type of task Minimum Maximum
      Authorized 1 32768
      Unauthorized 1 Parmlib
    • For MaxThreads, the limits are shown in Table 2. Parmlib represents the values that are specified at z/OS UNIX startup by the BPXPRMxx parmlib member.
      Table 2. Allowable thread limits for MaxThread
      Type of tasks Minimum Maximum
      Authorized 0 100000
      Unauthorized 0 Parmlib
  3. To determine the allowable ranges for pthread_created thread limits for nonauthorized callers, see sysconf (BPX1SYC, BPX4SYC) — Determine system configuration options.
  4. For information about setting initial thread limits and performance considerations, see MAXTHREADS in z/OS® UNIX System Services Planning.
  5. If the MaxThreadTasks limit is decreased below the number of tasks that are currently in use, pthread_exit_and_get requests fail until the number of tasks in use is less than or equal to the new limit.
  6. Setting the MaxThreads limit to zero inhibits the creation of pthread_created threads.
  7. Setting MaxThreads to be less than or equal to MaxThreadTasks prevents the queueing of pthread_create requests, and limits the number of MVS tasks that are attached for pthread_created threads to the MaxThreads value.
  8. If the MaxThreadTasks limit of a process is set below the number of MVS tasks that are already in use for pthread_created threads, the reduction of MVS tasks is completed as running threads terminate. The reduction of tasks is not synchronously carried out when the set_thread_limits service is invoked.
  9. For POSIX compliance, the MaxThreads limit for a process must be 64 or greater.

Related services

Characteristics and restrictions

None.

Examples

See BPX1STL (set_thread_limits) example.