cond_timed_wait (BPX1CTW, BPX4CTW) — Suspend a thread for a limited time or an event

Function

The cond_timed_wait callable service suspends the calling thread until any one of a set of events has occurred, or until a specified amount of time has passed.

Requirements

Parameters

Seconds

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains an unsigned integer that is the maximum number of seconds that the calling program is willing to wait for one of the specified events to occur.

Notes:

1. Seconds can be any value greater than or equal to 0, and less than or equal to 4 294 967 295. The value that is specified for Seconds is an unsigned integer.
2. The Seconds and Nanoseconds values are combined to determine the timeout value.

Nanoseconds

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains an unsigned integer that is the number of nanoseconds to be added to the value specified by Seconds.

Notes:

1. Nanoseconds can be any value greater than or equal to 0, and less than or equal to 1 000 000 000.
2. The Seconds and Nanoseconds values are combined to determine the timeout value.

Event_list

Supplied parameter

Type:

Integer

Length:

Fullword

Event_list specifies the name of a fullword that contains a value that determines which events are to cause the thread to resume processing.

The value that is contained in the event list is the inclusive OR of one or more of the following event values, which are defined by the BPXYCW macro:

CW_INTRPT

Suspends processing until a signal is sent to the thread. This is a cancellation point that is described in the usage notes of pthread_setintr (BPX1PSI, BPX4PSI) — Examine and change the interrupt state.

CW_CONDVAR

Suspends processing until some other thread in the process sends this one a CW_CONDVAR notification.

If the event list is zero, 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_timed_wait service sets the timer for the specified interval, and suspends thread processing until an event occurs, a signal arrives, or the time limit is reached.

Seconds_remaining

Supplied returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the cond_timed_wait returns an unsigned integer that is the number of seconds of unexpired time remaining in the time interval.

Note: The Seconds_remaining value is valid only when the return value is 0 or EINTR.

Nanoseconds_remaining

Supplied returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the cond_timed_wait returns an unsigned integer that is the number of nanoseconds of unexpired time remaining in the time interval.

Notes:

1. Nanoseconds_remaining can be any value greater than or equal to 0, and less than or equal to 1 000 000 000.
2. The nanoseconds remaining value is valid only when the return value is 0 or EINTR.

Return_Value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the service returns a 0 if a CW_CONDVAR event occurred, or -1 if it has not.

Return_Code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the service stores the return code. The cond_timed_wait service stores a return code only if the return value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. cond_timed_wait might return one of the following values in the Return_code parameter:

Error	Explanation
EAGAIN	No signal or event notification arrived within the specified timeout period. The thread resumed processing because the time interval expired. Note: If you specify a value of zero for both Seconds and Nanoseconds, and no event notification is pending when you call cond_timed_wait, the service returns this error.
EINTR	A signal caused the cond_timed_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_timed_wait call can accompany the return code: JRAlreadySetup, JRNanoSecondsTooBig, 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_timed_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. The cond_timed_wait service is similar to the POSIX function nanosleep(). (Refer to the POSIX standard for a description of nanosleep().) If you need the nanosleep() function, you can use cond_timed_wait to implement your own version.
2. If your program uses cond_timed_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_timed_wait. If the program invokes other callable services between cond_setup and cond_timed_wait, the cond_timed_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 can use the queue_interrupt service to "put back" the last signal delivered to the signal interface routine. A signal can arrive after the program that is running on the thread has called cond_setup, and before it gets a chance to call cond_timed_wait. The program may choose to "put back" the signal to defer handling of it until a later time.

3. If you use cond_setup to specify the events that are to cause the thread to resume processing, you must repeat the setup before each call to cond_wait or cond_timed_wait.
4. 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_timed_wait gives a return value of -1 with a return code of EMVSERR and a reason code of JRPswKeyNotValid.
5. 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.
6. If you do not include the CW_INTRPT event when you use cond_timed_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_wait (BPX1CWA, BPX4CWA) — Suspend a thread for 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.