pthread_exit_and_get (BPX1PTX, BPX4PTX) — Exit and get a new thread

Function

The pthread_exit_and_get callable service exits a thread, gets a new thread request to process, or both. To start a new thread request, see pthread_create (BPX1PTC, BPX4PTC) — Create a thread.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1PTX):	31-bit
AMODE (BPX4PTX):	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 BPX1PTX,(Status_field,
              Options_field,
              Signal_setup_userdata,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4PTX with the same parameters. The Status_field and Signal_setup_userdata parameters are doublewords.

Parameters

Status_field

Supplied parameter

Type:: Integer
Length:: Fullword (doubleword)

The name of a fullword (doubleword) field that contains the status of the exiting thread. This status is available to any other thread that uses the pthread_join service to wait for the termination of this thread.

Options_field

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains one of the following option values:

PTEXITTHREAD: Exit the calling thread. This causes the cleanup of system-related resources for the calling thread.
PTGETNEWTHREAD: Exit the last obtained thread and get the next available thread to process. The first invocation of pthread_exit_and_get from the pthread-creating task initialization routine must specify this option.
PTFAILIFLASTTHREAD: Exit the calling thread only if it is not the last thread in the process.

The default option value is PTEXITTHREAD. The option values are defined in the BPXYCONS macro; see BPXYCONS — Constants used by services. You can combine options by specifying a plus between them.

Signal_setup_userdata

Supplied parameter

Type:: Character string
Character set:: No restriction
Length:: Fullword (doubleword)

The name of a fullword (doubleword) field that contains 4 bytes (8 bytes) of user data that is normally supplied on the signal setup service, mvssigsetup. This field is used only when the PTGETNEWTHREAD option is specified. If this field contains a zero address, the signal setup user data is not changed for this thread. This field is ignored when the PTEXITTHREAD option is specified.

Return_Value

Returned parameter

Type:: Address
Length:: Fullword

The name of a fullword in which the service stores the return value. The return value varies depending on the options specified, as follows:

PTEXITTHREAD option value specified:
-1

The caller asked to exit the calling thread, but the thread could not be exited. For an explanation of the error, see Return_code and Reason_code.

0

The thread was successfully exited.
PTGETNEWTHREAD option value specified:
-1

The caller asked for a new thread to process, but the thread request could not be satisfied. No new thread requests can be handled by the calling task. For an explanation of the error, see Return_code and Reason_code.

>0
The address of the parameter list for the new thread request that is to be processed. The parameter list consists of the following:
- The user work area address that was specified on the pthread_create invocation.
- The user attribute area address that was specified on the pthread_create invocation.
- The address of an 8-byte field that contains the thread ID of the thread request.
- The address of a 4-byte thread run status field. For the possible status values and their definitions, see BPXYPTXL — Map the parameter list for pthread_create.
PTFAILIFLASTTHREAD option value specified:
-1

The caller asked to exit the calling thread only if it was not the last thread, but the thread could not be exited. For an explanation of the error, see Return_code and Reason_code.

0

The thread was successfully exited.

This parameter list is mapped by the BPXYPTXL macro; see BPXYPTXL — Map the parameter list for pthread_create. The storage for the list is supplied by the system and should not be modified or freed by the caller of pthread_exit_and_get.

Return_Code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the pthread_exit_and_get service stores the return code. The pthread_exit_and_get service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The pthread_exit_and_get service can return one of the following values in the Return_code parameter:

Return code	Explanation
EINVAL	One of the parameters contains a value that is not valid. The following reason codes can accompany the return code: JRInvOption, JRGetFirst, JRHeavyWeight, JRQuiesceInProcess, and JRLastThread.

Reason_Code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the pthread_exit_and_get service stores the reason code. The pthread_exit_and_get service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

The pthread_exit_and_get service provides a highly efficient mechanism for processing mediumweight threads. A mediumweight thread is a unit of work that causes reuse of MVS™ tasks. If a mediumweight thread exits, the task is still capable of processing another mediumweight thread request. The pthread_exit_and_get service provides pthread_exit with an option that obtains a new thread for its caller to process.
The first invocation of pthread_exit_and_get from the pthread-creating task initialization routine must specify the PTGETNEWTHREAD option. On the first invocation, a thread request is retrieved without the occurrence of a thread exit. All subsequent invocations result in a thread exit, following which the next available thread request is obtained. If the PTGETNEWTHREAD option is not specified on the first pthread_exit_and_get invocation, the service fails with a -1 return value, an EINVAL return code, and a JRGetFirst reason code.
Using the PTGETNEWTHREAD option can cause a failure if the process is being quiesced. If this happens, the pthread_exit_and_get service fails with a -1 return value, an EINVAL return code, and a JRQuiesceInProgress reason code. At this point, the caller should perform its own cleanup and return to the operating system to allow the task to terminate.
If the PTFAILIFLASTTHREAD option is specified and the pthread_exit_and_get is issued from the last thread, the thread is not exited and a JrLastThread reason code is returned with a -1 return value and an EINVAL return code. Any thread that has never issued a pthread_create or that was not created with pthread_create is considered the last thread when the PTFAILIFLASTTHREAD option is used.
When pthread_exit_and_get is used to get a new thread request, the signal environment is inherited from the creator of the thread. The signal state for the newly created thread is roughly analogous to that of a newly created process after the fork and exec services have been performed. The one exception is that the new thread inherits the setup state from the creator.
A successful invocation of pthread_exit_and_get awakens a thread that is waiting for the exiting thread, through the pthread_join service. The thread exit status that is specified on the pthread_exit_and_get call is made available to the waiting thread.
After pthread_exit_and_get is requested with the PTEXITTHREAD option from a given task, that task can no longer request z/OS UNIX services. An exception is the mvsprocclp service (BPX1MPC, BPX4MPC), which can be issued to undub the task. The caller should perform its own cleanup and return to the operating system to allow the task to end.
If pthread_exit_and_get fails for any reason (with a return value of -1), the caller should perform cleanup and return to the operating system to allow the task to end.
When a thread that specified the PTGETNEWTHREAD option is terminated with pthread_exit_and_get and the maximum allowable task limit is exceeded, a JRMaxTasks reason code is returned.
When this service is called from the initial pthread-creating task (IPT), it waits for all threads that were created with pthread_create to end.
For information about the pthread attribute area, see pthread_create (BPX1PTC, BPX4PTC) — Create a thread.
If you are going to use this service in a multiple-pthread environment, see Using threads with callable services.
If the PTEXITTHREAD option is used when a non-pthread_created thread exits, the status of the exiting thread is saved. This status is available to any other thread that uses the pthread_join service.

Related services

Examples

For an example using this callable service, see BPX1PTX (pthread_exit_and_get) example.