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
. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. 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. For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.
Usage notes for pthread_exit_and_get
- The pthread_exit_and_get service provides a highly efficient mechanism for processing medium-weight threads. A medium-weight thread is a unit of work that causes reuse of MVS™ tasks. If a medium-weight thread exits, the task is still capable of processing another medium-weight 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.
- Up to 10 medium-weight threads that have exited are allowed. The other tasks are terminated with Return Code EmvsErr and Reason code JrMaxTasks. In addition, these 10 threads waiting is only allowed to wait up to 30 seconds for new work. After 30 seconds, they will be terminated with Return Code EmvsErr and Reason code JrMaxTasks
- If environment variable _BPXK_UNUSEDTASKS is set to KEEP, then up to MaxThreadTasks can remain in a pthread_exit_and_get wait. In addition, there is no time limit on how long they can remain in the wait. The _BPXK_UNUSEDTASKS environment variable value is not propagated on spawn() with userid or setuid exec.