osi_sleep — Sleep until a resource is available

Function

The osi_sleep service waits for an osi_wakeup to be called with a matching Resource_id and Pfs_id.

Requirements

Operation	Environment
Authorization:	Problem or supervisor state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	Any
AMODE:	31-bit
ASC mode:	Any
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

     osi_sleep(OSI_structure,
               Resource_id,
               Time_interval,
               Return_value,
               Return_code,
               Reason_code);

Parameters

OSI_structure

Supplied parameter

Type:: OSI
Length:: Specified by OSI.osi_hdr.cblen.

OSI_structure contains information that is used by the OSI operations. The PFS receives this structure on each PFS interface operation.

Refer to Interface structures for C language servers and clients for a full description of this structure.

Resource_id

Supplied parameter

Type:: Token
Length:: Fullword

The Resource_id identifies the resource for which the thread is waiting.

Time_interval

Supplied parameter

Type:: Integer
Length:: Doubleword

The Time_interval is the maximum time for which osi_sleep will sleep. The value is specified in timer units and is rounded up to approximate seconds (the value of the high-order word). See z/Architecture® Principles of Operation for more information about timer units. The rounded-up value is added to the current time; therefore a very large time interval added to the current time could wrap to a very small number and result in an immediate timeout of osi_sleep. A value of 0 indicates that there is no time limit.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the osi_sleep service returns the results of the operation as one of the following:

Return_value: Meaning
-1: The operation was not successful.
0: The operation was successful, and the task was awakened by osi_wakeup.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the osi_sleep service stores the return code. The osi_sleep service can return one of the following values in the Return_code parameter only if Return_value is -1. Reason_code further qualifies the Return_code value.

Return_code	Explanation
EDEADLK	An FRR was active when the service was requested.
EINTR	The service was interrupted. Consult Reason_code to determine the exact reason the error occurred. The following reason codes can accompany the return code: JRSIGDURINGWAIT, JRTIMEOUT.
EINVAL	Incorrect parameter. Consult Reason_code to determine the exact reason the error occurred. The following reason codes can accompany the return code: JRBADOSI, JRBADPFSID.
EIO	The file system was unmounted while LFS serialization was dropped.
EMVSNOTUP	The system is being stopped.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the osi_sleep service stores the reason code. The osi_sleep service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value.

Usage notes

For additional information, see Waiting and posting.
All LFS serialization is dropped during an osi_sleep and reestablished after the osi_wakeup.
Before calling osi_sleep, the PFS must copy the osi_pfsid value to a location that is addressable by the task that will call osi_wakeup. It must be passed as the Pfs_id on osi_wakeup. The osi_pfsid value that is passed to the PFS is the same for all operations of this PFS. It is also passed as pfsi_pfsid during PFS initialization. This initialization value may be used on osi_wakeup instead of saving the OSI value.
The osi_wakeup service does not wake up a task that is not currently sleeping. If osi_wakeup is issued before osi_sleep for the same resource, the task sleeps until the next osi_wakeup for that resource. Therefore, the PFS must have sufficient logic and recovery to ensure that sleeping tasks are eventually awakened.
The address of the osi_sleep routine is passed to the PFS in the OSIT structure when the PFS is initialized.

Related services

osi_wakeup — Wake up OSI sleepers

Characteristics and restrictions

This routine must be used only on the task that made the vnode or VFS call.
An osi_sleep is not permitted if an FRR is established.