Lock Space Location (LOCKSL)

Operand 2: Character(1) scalar or null.

Built-in number for LOCKSL is 47.
LOCKSL (
        space_location   : address of space pointer(16)
        lock_request     : address OR
                           null operand
)

Description

The LOCKSL instruction can be used to lock space locations including teraspace locations. When operand 2 is not null, a thread scoped lock specified by operand 2 is requested by the current thread for the space location (operand 1). When operand 2 is null, the locks identified in the lock request template (operand 1) are requested by the current thread. By default, these locks are obtained thread scoped. Process and transaction control structure scoped locks are also supported for non-teraspace locations. A maximum of 4093 locations can be locked with one LOCKSL instruction.

Only the thread which is performing the lock operation and any other threads in the same process will ever conflict on teraspace location locks.

A space pointer machine object cannot be specified for operand 1.

The following is the format of operand 2 when not null:

For this format, if the requested lock cannot be immediately granted, the thread will enter a synchronous wait for the lock for a period of up to the interval specified by the process default time-out value. If the wait exceeds this time limit, a space location lock wait time-out  (hex 3A04) exception is signaled, and the requested lock is not granted.

During the wait, the process access state may be modified. This can occur if the process' instruction wait access state control attribute is set to allow access state modification, and if the process contains a single thread at the time of the lock request. Process access states are not modified for multi-threaded processes.

When operand 2 is null, the lock request template identified by operand 1 must be aligned on a 16-byte boundary. The format of operand 1 is as follows:

The lock state selection is located by adding the offset to lock state selection values above to operand 1.

Lock Allocation Procedure

A single Lock Space Location instruction can request the allocation of one or more lock states on one or more space locations. Space location locks are granted sequentially until all the locks requested are granted.

Note that when locks are materialized using Materialize Process Locks, (MATPRLK), if the process whose locks are being materialized is not the current process, then a null pointer value is returned for any lock on a teraspace storage location. If the current process is materializing its own locks, then a space pointer to the teraspace location, which was generated when the lock was acquired, is returned.

The wait time-out field establishes the maximum amount of time that a thread competes for the requested set of locks when the lock request type is synchronous. See Standard Time Format for additional information on the format of the wait time-out. The maximum wait time-out interval allowed is a value equal to (2⁴⁸ - 1) microseconds. Any value that indicates more time than the maximum wait time-out causes the maximum wait time-out to be used. If the wait time-out field is specified with a value of binary 0, then the value associated with the default wait time-out parameter in the process definition template establishes the time interval.

When a requested lock state cannot be immediately granted, any locks already granted by this Lock Space Location instruction are released, and the lock request type specified in the lock request template establishes the machine action. The lock request type values are described in the following paragraphs.

• Immediate request- If the requested space location locks cannot be granted immediately, this option causes the lock request not grantable  (hex 1A02) exception to be signaled. No space location locks are granted, and the lock request is canceled.

• Synchronous request- This option causes the thread requesting the locks to be placed in the wait state until all requested locks can be granted. If the locks cannot be granted in the time interval established by the wait time-out field specified in the lock request template, the space location lock wait time-out  (hex 3A04) exception is signaled to the requesting thread at the end of the interval. No locks are granted, and the lock request is canceled.

When:

• the thread requesting the locks is the only thread in the process at the time of the lock request, and
• the lock request type is synchronous, and
• the requested locks cannot be immediately granted,

If the thread requesting the locks belongs to a multi-threaded process, no access state modification is performed.

If the lock request type is synchronous and the invocation containing the Lock Space Location instruction is terminated, then the lock request is canceled.

Allocated space location locks are removed when the thread holding the locks terminates. If a thread terminates while waiting for a space location lock, the lock request is canceled.

The lock scope field and the lock scope object type field determine which scope all specified lock requests will be allocated to: a thread, a process or a transaction control structure.

• When lock scope has a value of lock is scoped to the current thread, the lock scope will be to the current thread.

  Note: Teraspace locations can only be scoped to the current thread, otherwise the template value invalid  (hex 3801) exception will be signaled.

• When lock scope has a value of lock is scoped to the lock scope object type and lock scope object type has a value of process containing the current thread, the lock scope will be the process containing the current thread.

• When lock scope has a value of lock is scoped to the lock scope object type and lock scope object type has a value of transaction control structure attached to the current thread, the lock scope will be the transaction control structure that is attached to the current thread. If the current thread does not have a transaction control structure attached, then the lock scope will be the process containing the current thread.

Locks scoped to a thread with a lock space object type value of process containing the current thread can never conflict with a lock scoped to its containing process, but may conflict with a lock scoped to a different process, a transaction control structure, or any other thread (depending on the lock states involved). Locks scoped to a thread with a lock space object type value of transaction control structure attached to the current thread can never conflict with a lock scoped to the transaction control structure, but may conflict with a lock scoped to a different transaction control structure, a process, or any other thread (depending on the lock states involved).

If lock scope object type has a value of transaction control structure attached to the current thread and the transaction control structure state does not allow objects to be locked on behalf of the transaction control structure, an object not eligible for operation  (hex 2204) exception is signaled.

Allocated process scoped locks and any thread scoped locks, allocated by the initial thread of the process, are released when the initial thread terminates. Allocated thread scoped locks are released when the thread terminates. If a thread requested a process scoped lock, the process will continue to hold that lock after termination of the requesting thread. If a thread requested a transaction control structure scoped lock, the transaction control structure will continue to hold that lock after the termination of the requesting thread.

The modify thread event mask option controls the state of the event mask in the thread executing this instruction. When the thread event mask is in the masked state, the machine does not schedule signaled event monitors in the thread. The event monitors continue to be signaled by the machine or other threads. When the thread event mask is modified to the unmasked state, event handlers are scheduled to handle those events that occurred while the thread was masked and those events occurring while in the unmasked state.

If the system security level machine attribute is hex 40 or greater and the thread is running in user state, then the modify thread event mask option is not allowed and a template value invalid  (hex 3801) exception is signalled.

When the modify thread event mask is set to 1, the previous thread event mask will be returned and the new thread event mask will take effect only when the space location lock(s) have been successfully granted. If the space location lock request is not successful, the previous thread event mask value is not returned, nor does the new thread event mask take effect.

The thread event mask values are validity checked only when the modify thread event mask is set to 1, and ignored otherwise. Valid masking values are:

Other values are reserved and must not be specified, otherwise a template value invalid  (hex 3801) exception is signaled.

The asynchronous signals processing option controls the action to be taken if an asynchronous signal is pending or received while in Lock Space Location wait. If an asynchronous signal that is not blocked or ignored is generated for the thread and the asynchronous signals processing option indicates allow asynchronous signals processing during Lock Space Location wait, the Lock Space Location wait will be terminated and an asynchronous signal terminated MI wait  (hex 4C01) exception is signaled. Otherwise, when the asynchronous signals processing option indicates do not allow asynchronous signals processing during Lock Space Location wait, the thread remains in the wait until all requested locks can be granted or until the wait time-out value for instruction expires.

If any exception is identified during the instruction's execution, any locks already granted by the instruction are released, and the lock request is canceled.

For each space location lock, counts are kept by lock state and by thread. When a lock request is granted, the appropriate lock count of each lock state specified is incremented by 1.

Authorization Required

• None

Lock Enforcement

• None

Exceptions

06 Addressing

• 0601 Space Addressing Violation
• 0602 Boundary Alignment
• 0603 Range
• 0607 Unsupported Space Use

08 Argument/Parameter

• 0801 Parameter Reference Violation

10 Damage Encountered

• 1004 System Object Damage State
• 1044 Partial System Object Damage

1A Lock State

• 1A02 Lock Request Not Grantable

1C Machine-Dependent

• 1C03 Machine Storage Limit Exceeded
• 1C06 Machine Lock Limit Exceeded

20 Machine Support

• 2002 Machine Check
• 2003 Function Check

22 Object Access

• 2202 Object Destroyed
• 2204 Object Not Eligible for Operation
• 2208 Object Compressed
• 220B Object Not Available

24 Pointer Specification

• 2401 Pointer Does Not Exist
• 2402 Pointer Type Invalid

2E Resource Control Limit

• 2E01 User Profile Storage Limit Exceeded

32 Scalar Specification

• 3201 Scalar Type Invalid
• 3203 Scalar Value Invalid

36 Space Management

• 3601 Space Extension/Truncation

38 Template Specification

• 3801 Template Value Invalid

3A Wait Time-Out

• 3A04 Space Location Lock Wait Time-Out

44 Protection Violation

• 4401 Object Domain or Hardware Storage Protection Violation
• 4402 Literal Values Cannot Be Changed

4C Signals Management

• 4C01 Asynchronous Signal Terminated MI Wait