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

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 complete list of possible return code values, see 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 the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

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.

If any caller, authorized or nonauthorized, attempts to set a limit outside the allowable ranges (see Table 1), the set_thread_limits service returns with a return code of EINVAL and a reason code of JRSTLTasksInvalid or JRSTLThreadsInvalid.

Table 1. Allowable thread limits for calling processes
	MaxThreadTasks		MaxThreads
	Min	Max	Min	Max
Authorized	1	32768	0	100000
Unauthorized	1	Parmlib	0	Parmlib
Note: Parmlib represents the values that are specified at z/OS UNIX startup by the BPXPRMxx parmlib member.

To determine the allowable ranges for pthread_created thread limits for non-authorized callers, see sysconf (BPX1SYC, BPX4SYC) — Determine system configuration options.
For information on setting initial thread limits and performance considerations, see the following publications:
- MAXTHREADS in z/OS UNIX System Services Planning
- z/OS MVS Initialization and Tuning Reference
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.
Setting the MaxThreads limit to zero inhibits the creation of pthread_created threads.
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.
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.
For POSIX compliance, the MaxThreads limit for a process must be 64 or greater.

Related services

Characteristics and restrictions

There are no restrictions on the use of the set_thread_limits service.

Examples

For an example using this callable service, see BPX1STL (set_thread_limits) example.