pthread_quiesce (BPX1PTQ, BPX4PTQ) — Quiesce threads in a process

Function

The pthread_quiesce callable service performs quiesce or query functions on threads. Depending on the function that is specified, pthread_quiesce queries the thread environment in the current process, or synchronously quiesces all threads in the current process (except for the calling thread, which returns when all threads have been quiesced).

Requirements

Parameters

Quiesce_type

Supplied parameter

Type:

Integer

Length:

Fullword

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

QUIESCE_TERM

Terminates all threads (except the invoking thread) that were created with pthread_create and IPT threads, allowing the signal interface routine to receive control when the quiesce request is delivered.

QUIESCE_FORCE

Terminates all threads (except the invoking thread) that were created with pthread_create, and IPT threads that do not allow the signal interface routine to receive control when the quiesce request is delivered.

PTHREAD_QUERY

Counts the number of threads that were created with pthread_create or IPT threads and returns the count in Return_value.

QUIESCE_FREEZE

Freezes all threads (except the invoking thread) in the process, including threads that were created with pthread_create, IPT, and MVS™ dubbed tasks. The signal interface routine is allowed to receive control when the quiesce event is delivered.

QUIESCE_UNFREEZE

Continues execution of all threads (except the invoking thread) in the process that are in a frozen state.

FREEZE_THIS_THREAD

Places the invoking thread into a frozen state, in response to a QUIESCE_FREEZE request.

The Quiesce_type values are defined in the BPXYCONS macro; see BPXYCONS — Constants used by services.

User_data

Supplied parameter

Type:

Character string

Length:

Fullword (doubleword)

The name of a fullword (doubleword) that is to be passed to the signal interface routine when the quiesce request is delivered.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the pthread_quiesce service places the return value. The return value varies depending on the Quiesce_type:

• PTHREAD_QUERY quiesce type specified:

  -1

  The caller asked to query the number of threads that were created with pthread_create and IPT threads in the process, but the request could not be completed. For an explanation of the error, see the return code and reason code.

  0

  The calling thread is the initial pthread-creating task (IPT), and no other threads that were created with pthread_create exist in the current process.

  1

  The calling thread is created with pthread_create, not the IPT, and no other threads that were created with pthread_create or IPT threads exist in the current process.

  >1

  The value indicates the number of threads that were created with pthread_create and IPT threads in the current process.

• All other quiesce types specified:

  -1

  The caller asked to quiesce a thread in the current process, but the target threads may not all have been quiesced. For an explanation of the error, see the return code and reason code.

  0

  The target threads in the current process were successfully quiesced.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the pthread_quiesce service stores the return code. The pthread_quiesce service returns a 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 pthread_quiesce service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	The value specified for Quiesce_type was incorrect. The following reason code can accompany the return code: JRQuiesceTypeInvalid.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the pthread_quiesce service stores the reason code. The pthread_quiesce 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

1. Requesting pthread_quiesce with the QUIESCE_TERM or QUIESCE_FORCE options delivers a quiesce request to the IPT and all pthread_created threads in the process. When Quiesce_type is QUIESCE_TERM, the request is delivered to each thread by the signal interface routine (SIR) if the process is set up to intercept the quiesce request. If the process is not set up for quiesce request interception, or if Quiesce_type is QUIESCE_FORCE, the kernel performs the quiesce request for each thread. For details on how to intercept quiesce requests, see mvssigsetup (BPX1MSS, BPX4MSS) — Set up MVS signals.
2. The kernel issues 422 abends when performing the termination quiesce request. If the request is intercepted by the user-defined SIR, it should perform whatever cleanup is necessary, and then issue the pthread_exit_and_get service to end the thread.
3. Requesting pthread_quiesce with the QUIESCE_TERM or QUIESCE_FORCE options from a thread that is not the IPT, or that was not created with the pthread_create service, has no effect on any threads in the process; and pthread_quiesce returns with a 0 return value.
4. The pthread_quiesce service should be requested with one of the terminating options before an exit (BPX1EXI, BPX4EXI) to prevent the other threads in the process from receiving an asynchronous abend.
5. When requested with one of the terminating options, the pthread_quiesce service posts all MVS tasks that are in pthread_exit_and_get (BPX1PTX, BPX4PTX) waiting for more work. The pthread_exit_and_get service returns to the caller with a -1 return value. The caller can then clean up the task-related resources before the normal end (SVC 3) of the task.
6. If the pthread_quiesce service is invoked when Quiesce_type is PTHREAD_QUERY from a thread that was not created with pthread_create and is not an IPT thread, pthread_quiesce returns with a 0 return value.
7. The use of QUIESCE_FREEZE is not limited to the IPT and pthread_created threads. This option causes a quiesce event to be delivered to every other thread in the process. Upon return from pthread_quiesce, all threads in the process are no longer executing and are in a "frozen state".
8. If the target thread is intercepting quiesce events (see mvssigsetup (BPX1MSS, BPX4MSS) — Set up MVS signals), the signal interface routine gains control and is expected to either issue the queue_interrupt service (this is not a good time to freeze this thread) or issue the pthread_quiesce service with the FREEZE_THIS_THREAD option. However, since the quiescer is waiting for all threads to be placed into a frozen state, the pthread_quiesce service should be issued as soon as possible. If the target thread is not intercepting, the kernel places the thread into a frozen state.
9. The FREEZE_THIS_THREAD function places the thread into a frozen state only if a freeze request is pending on the calling thread. If a request is not pending, the FREEZE_THIS_THREAD function does not suspend execution. Control is immediately returned to the caller with a return code of zero.
10. When you want to restart the process, use the pthread_quiesce service with the QUIESCE_UNFREEZE option. All threads that are found to be in a frozen state are restarted.

Related services

• mvssigsetup (BPX1MSS, BPX4MSS) — Set up MVS signals
• pthread_create (BPX1PTC, BPX4PTC) — Create a thread