Lock Object (LOCK)

Instruction Syntax

Built-in number for LOCK is 46.
LOCK (
      lock_request_template   : address
)

Description:

Locks for system objects identified by system pointers in the space identified by operand 1 are allocated to the requesting thread or its containing process or a transaction control structure. The lock state desired for each object is specified by a value associated with each system pointer in the lock request template (operand 1).

The lock request template must be aligned on a 16-byte boundary. The format is as follows:

The lock object template extension is only present if template extension specified is indicated above. Otherwise, the object(s) to be locked should immediately follow.

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

A single Lock Object instruction can request the allocation of one or more lock states on one or more objects. Locks are allocated sequentially until all locks requested are allocated.

When two or more threads are competing for a conflicting lock allocation on a system object, the machine attempts to first satisfy the lock allocation request of the thread with the highest priority. Within that priority, the machine attempts to satisfy the request that has been waiting longest.

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 system object lock, counts are kept by lock state and by thread, process, or transaction control structure. When a lock request is granted, the appropriate lock count(s) of each lock state specified is incremented by 1.

If a transfer of a lock from another thread causes a previously unsatisfied lock request to become satisfied, the lock request and the transfer lock are treated independently relative to lock accounting. The appropriate lock counts are incremented for both the lock request and the transfer lock function.

The offset to lock state selection values specifies an offset from the beginning of the lock request. This offset is used to locate the lock state selection values.

The wait time-out value for instruction field establishes the maximum amount of time that a thread competes for the requested set of locks when lock request type is either synchronous or asynchronous. When lock scope object type has a value of binary 1, the lock wait time interval value for the transaction control structure attached to the current thread is used to establish the maximum amount of time that the thread competes for the set of locks. See Standard Time Format for additional information on the format of the wait time-out value for instruction.

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 field in the process definition template establishes the time interval.

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

• Immediate request– If the requested locks cannot be granted immediately, this option causes the lock request not grantable (hex 1A02) exception to be signaled. No 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 lock time-out (hex 3A02) exception is signaled to the requesting thread at the end of the interval. No locks are granted, and the lock request is canceled.
• Asynchronous request– This option allows the requesting thread to proceed with execution while the machine asynchronously attempts to satisfy the lock request.

When:

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

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 instruction is terminated, then the lock request is canceled.

If an asynchronous lock request is satisfied, then the object locked (hex 000A,01,01) event is signaled to the requesting thread. If the request is not satisfied in the time interval established by the wait time-out field specified in the lock request template, the asynchronous lock wait timeout (hex 000A,04,01) event is signaled to the requesting thread. No locks are granted, and the lock request is canceled. If an object is destroyed while a thread has a pending request to lock the object, the object destroyed (hex 000A,02,01) event is signaled to the waiting thread. These events are signaled to the requesting thread, regardless of the scope of the requested lock.

If the lock request type is asynchronous and the invocation containing the Lock Object instruction is terminated, then the lock request remains active.

The lock scope field and the lock scope object type field determines which scope all specified lock requests will be allocated to, either a thread, process or transaction control structure. When lock scope has a value of binary 0 and lock scope object type has a value of 0, the lock scope will be the process containing the current thread. When lock scope has a value of binary 0 and lock scope object type has a value of 1, 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. When lock scope has a value of binary 1 the lock scope will be to the current thread and the value of the lock scope object type will be used to determine how lock conflicts are detected. Locks scoped to a thread with a lock scope 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 scope 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 scope locks are released when the process terminates. Allocated thread scope locks are released when the thread terminates. If a thread requested a process scope lock, the process will continue to hold that lock after termination of the requesting thread. If a thread requested a transaction control structure scope lock, the transaction control structure will continue to hold that lock after the termination of the requesting thread.

If a thread is terminated while waiting for a lock with a lock request type of either synchronous or asynchronous, the lock request is canceled regardless of the scope of the requested lock.

The modify thread event mask option controls the state of the event mask in the thread executing this instruction. If the 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 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. The number of events retained while the thread is masked is specified by the attributes of the event monitor associated with the thread.

A lock request with an asynchronous lock request type cannot have the modify thread event mask option set to binary 1.

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 binary 1, the previous thread event mask will be returned and the new thread event mask will take effect only when the lock(s) have been successfully granted. If the lock request is not successful, the previous thread event mask value is not returned, nor does the new thread event mask take effect.

Whether masking or unmasking the current thread, the new mask takes effect upon completion of a satisfied lock object.

Valid masking values are:

0

Masked

256

Unmasked

Other values are reserved. If any other values are specified, a template value invalid (hex 3801) exception is signaled.

The thread is automatically masked by the machine when event handlers are invoked. If the thread is unmasked in the event handler, other events can be handled if another enabled event monitor within that thread is signaled. If the thread is masked when it exits from the event handler, the machine explicitly unmasks the thread.

The asynchronous signals processing option controls the action to be taken if an asynchronous signal is pending or received while in Lock 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 wait, the Lock 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 wait, the thread remains in the wait until all requested locks can be granted or until the wait time-out value for instruction expires.

Authorization Required

• Some authority or ownership
  • Objects to be locked
• Execute
  • Contexts referenced for address resolution

Lock Enforcement

• Materialize
  • Contexts referenced for address resolution

Exceptions

• 06 Addressing
  • 0601 Space Addressing Violation
  • 0602 Boundary Alignment
  • 0603 Range
• 08 Argument/Parameter
  • 0801 Parameter Reference Violation
• 0A Authorization
  • 0A01 Unauthorized for Operation
• 10 Damage Encountered
  • 1004 System Object Damage State
  • 1005 Authority Verification Terminated Due to Damaged Object
  • 1044 Partial System Object Damage
• 1A Lock State
  • 1A01 Invalid 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
  • 2201 Object Not Found
  • 2202 Object Destroyed
  • 2203 Object Suspended
  • 2204 Object Not Eligible for Operation
  • 2207 Authority Verification Terminated Due to Destroyed Object
  • 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
• 36 Space Management
  • 3601 Space Extension/Truncation
• 38 Template Specification
  • 3801 Template Value Invalid
• 3A Wait Time-Out
  • 3A02 Lock 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