cond_wait (BPX1CWA, BPX4CWA) — Suspend a thread for an event
Function
The cond_wait callable service allows the caller's thread to suspend processing until any one of a set of events has occurred.
Requirements
Operation | Environment |
---|---|
Authorization: | Problem program or supervisor state, PSW key when the process was created (not PSW key 0) |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1CWA): | 31-bit |
AMODE (BPX4CWA): | 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
|
AMODE 64 callers use BPX4CWA with the same parameters.
Parameters
- Event_list
- Supplied returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains a value that determines which events will cause the thread to resume processing.
The value contained in Event_list is the inclusive OR of one or more of the following event values defined by the BPXYCW macro.- CW_INTRPT
- Suspends processing until a signal is sent to the thread.
- CW_CONDVAR
- Suspends processing until some other thread in the process sends this one a CW_CONDVAR event notification.
An Event_list of zero means that the caller has used the cond_setup service to specify the events, and the thread is already eligible to be notified of events. In this case, the cond_wait service suspends thread processing until an event occurs or a signal arrives.
- Return_Value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the service returns a 0 a CW_CONDVAR event occurred, or -1 otherwise.
- Return_Code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the service stores the return code. The cond_wait service stores a 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 cond_wait service may return one of the following values in the Return_code parameter:Error Explanation EINTR A signal caused the cond_wait service to resume processing of the thread. Note: The signal handler has already run.EINVAL The system determined that one or more of the parameters that were passed to the service are in error. The following reason codes unique to the cond_wait call can accompany the return code: JRAlreadySetup, JRNotSetup, JRUndefEvents. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the service routine stores the reason code. The cond_wait service stores a reason code only when the return value is -1. The reason code further qualifies the return code value. See z/OS UNIX System Services Messages and Codes for the reason codes.
Usage notes
- If your program uses cond_wait to wait for events that it specified
by calling cond_setup, it must not call any other z/OS UNIX services
between the calls to cond_setup and cond_wait. If the program invokes
other callable services between cond_setup and cond_wait, the cond_wait
callable service fails with a return value of -1,
a return code of EINVAL, and a reason code of JRNotSetup.
The only exception to this is the queue_interrupt service. You may use the queue_interrupt service to "put back" the last signal delivered to the signal interface routine. A signal may arrive after the program that is running on the thread has called cond_setup and before it gets a chance to call cond_wait. The program may choose to "put back" the signal to defer handling it until a later time.
If you use cond_setup to specify the events that will cause the thread to resume processing, you must repeat the setup before each call to cond_wait or cond_timed_wait.
- If the caller has a PSW key of 0 or a key that is different from the one that was in effect when the process was created, cond_wait gives a return value of -1, a return code of EMVSERR, and a reason code of JRPswKeyNotValid.
- If the thread has been set up for signals, the cond_timed_wait service must run on the same request block (RB) that was used when the setup for signals was performed.
- If you do not include the CW_INTRPT event when you use cond_wait,
some services that are used by other threads or processes cannot cause
the waiting thread to resume processing. In particular, the following
services do not cause an event notification unless CW_INTRPT is specified
in the event list:
- kill
- pthread_cancel
- pthread_kill
- pthread_quiesce
Related services
- cond_cancel (BPX1CCA, BPX4CCA) — Cancel interest in events
- cond_post (BPX1CPO, BPX4CPO) — Post a thread for an event
- cond_setup (BPX1CSE, BPX4CSE) — Set up to receive event notifications
- cond_timed_wait (BPX1CTW, BPX4CTW) — Suspend a thread for a limited time or an event
- queue_interrupt (BPX1SPB, BPX4SPB) — Return the last interrupt delivered
Characteristics and restrictions
See The relationship of z/OS UNIX signals to callable services.
Examples
See BPX1CWA (cond_wait) example for an example using this callable service.