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
Operation |
Environment |
Authorization: |
Supervisor state or problem state, any PSW key |
Dispatchable unit mode: |
Task |
Cross memory mode: |
PASN = HASN |
AMODE (BPX1PTQ): |
31-bit |
AMODE (BPX4PTQ): |
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 BPX1PTQ (Quiesce_type,
User_data,
Return_value,
Return_code,
Reason_code)
|
AMODE 64 callers use BPX4PTQ with the same parameters.
User_data is a doubleword.
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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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".
- 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.
- 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.
- 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.