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

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

1. 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.

2. 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.
3. 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.
4. 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.