LOCK (ObjectScript)

LOCK without Arguments

The argumentless LOCK releases (unlocks) all locks currently held by the process in all namespaces. This includes exclusive and shared locks, both local and global. It also includes all accumulated incremental locks. For example, if there are three incremental locks on a given lock name, InterSystems IRIS releases all three locks and removes the lock name entry from the lock table.

If you issue an argumentless LOCK during a transaction, InterSystems IRIS places all locks currently held by the process in a Delock state until the end of the transaction. When the transaction ends, InterSystems IRIS releases the locks and removes the corresponding lock name entries from the lock table.

The following example applies various locks during a transaction, then issues an argumentless LOCK to release all of these locks. The locks are placed in a Delock state until the end of the transaction. The HANG commands give you time to check the lock’s ModeCount in the Lock Table:

  TSTART
  LOCK +^a(1)      // ModeCount: Exclusive
  HANG 2
  LOCK +^a(1)#"E"  // ModeCount: Exclusive/1+1e
  HANG 2
  LOCK +^a(1)#"S"  // ModeCount: Exclusive/1+1e,Shared
  HANG 2
  LOCK             // ModeCount: Exclusive/1+1e->Delock,Shared->Delock
  HANG 10
  TCOMMIT          // ModeCount: locks removed from table

Argumentless LOCK releases all locks held by the process without applying any locks. Completion of a process also releases all locks held by that process.

LOCK with Arguments

LOCK with arguments specifies one or more lock names on which to perform locking and unlocking operations. What lock operation InterSystems IRIS performs depends on the lock operation indicator argument you use:

• LOCK lockname unlocks all locks previously held by the process in all namespaces, then applies a lock on the specified lock name(s).

• LOCK +lockname applies a lock on the specified lock name(s) without unlocking any previous locks. This allows you to accumulate different locks, and allows you to apply incremental locks to the same lock.

• LOCK -lockname performs an unlock operation on the specified lock name(s). Unlocking decrements the lock count for the specified lock name; when this lock count decrements to zero, the lock is released.

A lock operation may immediately apply the lock, or it may place the lock request on a wait queue pending the release of a conflicting lock by another process. A waiting lock request may time out (if you specify a timeout) or may wait indefinitely (until the end of the process).

pc

An optional postconditional expression that can make the command conditional. InterSystems IRIS executes the LOCK command if the postconditional expression is true (evaluates to a nonzero numeric value). InterSystems IRIS does not execute the command if the postconditional expression is false (evaluates to zero). You can specify a postconditional expression on an argumentless LOCK command or a LOCK command with arguments. For further details, refer to Command Postconditional Expressions in Using ObjectScript.

lock operation indicator

The lock operation indicator is used to apply (lock) or remove (unlock) a lock. It can be one of the following values:

If your LOCK command contains multiple comma-separated lock arguments, each lock argument can have its own lock operation indicator. InterSystems IRIS parses this as multiple independent LOCK commands.

lockname

A lockname is the name of a lock for a data resource; it is not the data resource itself. That is, your program can specify a lock named ^a(1) and a variable named ^a(1) without conflict. The relationship between the lock and the data resource is a programming convention; by convention, processes must acquire the lock before modifying the corresponding data resource.

Lock names are case-sensitive. Lock names follow the same naming conventions as the corresponding local variables and global variables. A lock name can be subscripted or unsubscripted. Lock subscripts have the same naming conventions and maximum length and number of levels as variable subscripts. In InterSystems IRIS, the following are all valid and unique lock names: a, a(1), A(1), ^a, ^a(1,2), ^A(1,1,1). For further details, see the Variables chapter of Using ObjectScript.

Lock names can be local or global. A lock name such as A(1) is a local lock name. It applies only to that process, but does apply across namespaces. A lock name that begins with a caret (^) character is a global lock name; the mapping for this lock follows the same mapping as the corresponding global, and thus can apply across processes, controlling their access to the same resource. (See Global Structure in Using Globals.)

A lock name can represent a local or global variable, subscripted or unsubscripted. It can be an implicit global reference, or an extended reference to a global on another computer. (See Global Structure in Using Globals.)

The data resource corresponding to a lock name does not need to exist. For example, you may lock the lock name ^a(1,2,3) whether or not a global variable with the same name exists. Because the relationship between locks and data resources is an agreed-upon convention, a lock may be used to protect a data resource with an entirely different name.

locktype

A letter code specifying the type of lock to apply or remove. locktype is an optional argument; if you omit locktype, the lock type defaults to an exclusive non-escalating lock. If you omit locktype, you must omit the pound sign (#) prefix. If you specify locktype, the syntax for lock type is a mandatory pound sign (#), followed by quotation marks enclosing one or more lock type letter codes. Lock type letter codes can be specified in any order and are not case-sensitive. The following are the lock type letter codes:

• S: Shared lock

  Allows multiple processes to simultaneously hold nonconflicting locks on the same resource. For example, two (or more) processes may simultaneously hold shared locks on the same resource, but an exclusive lock limits the resource to one process. An existing shared lock prevents all other processes from applying an exclusive lock, and an existing exclusive lock prevents all other processes from applying a shared lock on that resource. However, a process can first apply a shared lock on a resource and then the same process can apply an exclusive lock on the resource, upgrading the lock from shared to exclusive. Shared and Exclusive lock counts are independent. Therefore, to release such a resource it is necessary to release both the exclusive lock and the shared lock. All locking and unlocking operations that are not specified as shared (“S”) default to exclusive.

  A shared lock may be incremental; that is, a process may issue multiple shared locks on the same resource. You may specify a shared lock as escalating (“SE”) when locking and unlocking. When unlocking a shared lock, you may specify the unlock as immediate (“SI”) or deferred (“SD”). To view the current shared locks with their increment counts for escalating and non-escalating lock types, refer to the system-wide lock table, described in the “Lock Management” chapter of Using ObjectScript.

• E: Escalating lock

  Allows you to apply a large number of concurrent locks without overflowing the lock table. By default, locks are non-escalating. When applying a lock, you can use locktype “E” to designate that lock as escalating. When releasing an escalating lock, you must specify locktype “E” in the unlock statement. You can designate both exclusive locks and shared (“S”) locks as escalating.

  Commonly, you would use escalating locks when applying a large number of concurrent locks at the same subscript level. For example LOCK +^mylock(1,1)#"E",+^mylock(1,2)#"E",+^mylock(1,3)#"E"....

  The same lock can be concurrently applied as a non-escalating lock and as an escalating lock. For example, ^mylock(1,1) and ^mylock(1,1)#"E". InterSystems IRIS counts locks issued with locktype “E” separately in the lock table. For information on how escalating and non-escalating locks are represented in the lock table, refer to the “Lock Management” chapter of Using ObjectScript.

  When the number of “E” locks at a subscript level reaches a threshold number, the next “E” lock requested for that subscript level automatically attempts to lock the parent node (the next higher subscript level). If it cannot, no escalation occurs. If it successfully locks the parent node, it establishes one parent node lock with a lock count corresponding to the number of locks at the lower subscript level, plus 1. The locks at the lower subscript level are released. Subsequent “E” lock requests to the lower subscript level further increment the lock count of this parent node lock. You must unlock all “E” locks that you have applied to decrement the parent node lock count to 0 and de-escalate to the lower subscript level. The default lock threshold is 1000 locks; lock escalation occurs when the 1001st lock is requested.

  Note that once locking is escalated, lock operations preserve only the number of locks applied, not what specific resources were locked. Therefore, failing to unlock the same resources that you locked can cause “E” lock counts to get out of sync.

  In the following example, lock escalation occurs when the program applies the lock threshold + 1 “E” lock. This example shows that lock escalation both applies a lock on the next-higher subscript level and releases the locks on the lower subscript level:

  Main
    TSTART
    SET thold=$SYSTEM.SQL.Util.GetOption("LockThreshold") 
    WRITE "lock escalation threshold is ",thold,!
    SET almost=thold-5
    FOR i=1:1:thold+5 { LOCK +dummy(1,i)#"E"
       IF i>almost {
         IF ^$LOCK("dummy(1,"_i_")","OWNER") '= "" {WRITE "lower level lock applied at ",i,"th lock ",! }
         ELSEIF ^$LOCK("dummy(1)","OWNER") '= ""   {WRITE "lock escalation",!
                                                    WRITE "higher level lock applied at ",i,"th lock ",!
                                                    QUIT }
         ELSE {WRITE "No locks applied",! }
       }
    }
    TCOMMIT

  

  Note that only “E” locks are counted towards lock escalation. The following example applies both default (non-“E”) locks and “E” locks on the same variable. Lock escalation only occurs when the total number of “E” locks on the variable reaches the lock threshold:

  Main
    TSTART
    SET thold=$SYSTEM.SQL.Util.GetOption("LockThreshold")
    WRITE "lock escalation threshold is ",thold,!
    SET noE=17
    WRITE "setting ",noE," non-escalating locks",!
    FOR i=1:1:thold+noE { IF i < noE {LOCK +a(6,i)}
                    ELSE {LOCK +a(6,i)#"E"}
      IF ^$LOCK("a(6)","OWNER") '= "" {
         WRITE "lock escalation on lock a(6,",i,")",!
         QUIT }
    }
    TCOMMIT

  

  Unlocking “E” locks is the reverse of the above. When locking is escalated, unlocks at the child level decrement the lock count of the parent node lock until it reaches zero (and is unlocked); these unlocks decrementing a count, they are not matched to specific locks. When the parent node lock count reaches 0, the parent node lock is removed and “E” locking de-escalates to the lower subscript level. Any subsequent locks at the lower subscript level create specific locks at that level.

  The “E” locktype can be combined with any other locktype. For example, “SE”, “ED”, “EI”, “SED”, “SEI”. When combined with the “I” locktype it permits unlocks of “E” locks to occur immediately when invoked, rather than at the end of the current transaction. This “EI” locktype can minimize situations where locking is escalated.

  Commonly, “E” locks are automatically applied for SQL INSERT, UPDATE, and DELETE operations within a transaction. However, there are specific limitations on SQL data definition structures that support “E” locking. Refer to the specific SQL commands for details.

• I: Immediate unlock

  Immediately releases a lock, rather than waiting until the end of a transaction:

  • Specifying “I” when unlocking a non-incremented (lock count 1) lock immediately releases the lock. By default, an unlock does not immediately release a non-incremented lock. Instead, when you unlock a non-incremented lock InterSystems IRIS maintains that lock in a delock state until the end of the transaction. Specifying “I” overrides this default behavior.

  • Specifying “I” when unlocking an incremented lock (lock count > 1) immediately releases the incremental lock, decrementing the lock count by 1. This is the same behavior as a default unlock of an incremented lock.

  The “I” locktype is used when performing an unlock during a transaction. It has the same effect on InterSystems IRIS unlock behavior whether the lock was applied within the transaction or outside of the transaction. The “I” locktype performs no operation if the unlock occurs outside of a transaction. Outside of a transaction, an unlock always immediately releases a specified lock.

  “I” can only be specified for an unlock operation; it cannot be specified for a lock operation. “I” can be specified for an unlock of a shared lock (#"SI") or an exclusive lock (#"I"). Locktypes “I” and “D” are mutually exclusive. “IE” can be used to immediately unlock an escalating lock.

  This immediate unlock is shown in the following example:

    TSTART
    LOCK +^a(1)      // apply lock ^a(1)
    LOCK -^a(1)      // remove (unlock) ^a(1)
                     // An unlock without a locktype defers the unlock
                     // of a non-incremented lock to the end of the transaction.
    WRITE "Default unlock within a transaction.",!,"Go look at the Lock Table",!
    HANG 10          // This HANG allows you to view the current Lock Table
    LOCK +^a(1)      // reapply lock ^a(1)
    LOCK -^a(1)#"I"  // remove (unlock) lock ^a(1) immediately
                     // this removes ^a(1) from the lock table immediately
                     // without waiting for the end of the transaction
    WRITE "Immediate unlock within a transaction.",!,"Go look at the Lock Table",!
    HANG 10          // This HANG allows you to view the current Lock Table
                     // while still in the transaction
    TCOMMIT

  

• D: Deferred unlock

  Controls when an unlocked lock is released during a transaction. The unlock state is deferred to the state of the previous unlock of that lock. Therefore, specifying locktype “D” when unlocking a lock may result in either an immediate unlock or a lock placed in delock state until the end of the transaction, depending on the history of the lock during that transaction. The behavior of a lock that has been locked/unlocked more than once differs from the behavior of a lock that has only been locked once during the current transaction.

  The “D” unlock is only meaningful for an unlock that releases a lock (lock count 1), not an unlock that decrements a lock (lock count > 1). An unlock that decrements a lock is always immediately released.

  “D” can only be specified for an unlock operation. “D” can be specified for a shared lock (#"SD") or an exclusive lock (#"D"). “D” can be specified for a escalating (“E”) lock, but, of course, the unlock must also be specified as escalating (“ED”). Lock types “D” and “I” are mutually exclusive.

  This use of “D” unlock within a transaction is shown in the following examples. The HANG commands give you time to check the lock’s ModeCount in the Lock Table.

  If the lock was only applied once during the current transaction, a “D” unlock immediately releases the lock. This is the same as “I” behavior. This is shown in the following example:

    TSTART
    LOCK +^a(1)      // Lock Table ModeCount: Exclusive
    LOCK -^a(1)#"D"  // Lock Table ModeCount: null (immediate unlock)
    HANG 10
    TCOMMIT

  

  If the lock was applied more than once during the current transaction, a “D” unlock reverts to the prior unlock state.

  • If the last unlock was a standard unlock, the “D” unlock reverts unlock behavior to that prior unlock’s behavior — to defer unlock until the end of the transaction. This is shown in the following examples:

      TSTART
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK -^a(1)      // Lock Table ModeCount: Exclusive
         WRITE "1st unlock",! HANG 5
      LOCK -^a(1)#"D"  // Lock Table ModeCount: Exclusive->Delock
         WRITE "2nd unlock",! HANG 5
      TCOMMIT

    

      TSTART
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK -^a(1)      // Lock Table ModeCount: Exclusive->Delock
         WRITE "1st unlock",! HANG 5
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK -^a(1)#"D"  // Lock Table ModeCount: Exclusive->Delock
         WRITE "2nd unlock",! HANG 5
      TCOMMIT

    

      TSTART
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK -^a(1)#"I"  // Lock Table ModeCount: Exclusive/2
         WRITE "1st unlock",! HANG 5
      LOCK -^a(1)      // Lock Table ModeCount: Exclusive
         WRITE "2nd unlock",! HANG 5
      LOCK -^a(1)#"D"  // Lock Table ModeCount: Exclusive->Delock
         WRITE "3rd unlock",! HANG 5
      TCOMMIT

    

  • If the last unlock was an “I” unlock, the “D” unlock reverts unlock behavior to that prior unlock’s behavior — to immediately unlock the lock. This is shown in the following examples:

      TSTART
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK -^a(1)#"I"  // Lock Table ModeCount: null (immediate unlock)
         WRITE "1st unlock",! HANG 5
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK -^a(1)#"D"  // Lock Table ModeCount: null (immediate unlock)
         WRITE "2nd unlock",! HANG 5
      TCOMMIT

    

      TSTART
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK -^a(1)#"I"  // Lock Table ModeCount: Exclusive
         WRITE "1st unlock",! HANG 5
      LOCK -^a(1)#"D"  // Lock Table ModeCount: null (immediate unlock)
         WRITE "2nd unlock",! HANG 5
      TCOMMIT

    

  • If the last unlock was a “D” unlock, the “D” unlock follows the behavior of the last prior non-“D” lock:

      TSTART
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK -^a(1)#"D"  // Lock Table ModeCount: Exclusive
         WRITE "1st unlock",! HANG 5
      LOCK -^a(1)#"D"  // Lock Table ModeCount: null (immediate unlock)
         WRITE "2nd unlock",! HANG 5
      TCOMMIT

    

      TSTART
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK -^a(1)      // Lock Table ModeCount: Exclusive/2
         WRITE "1st unlock",! HANG 5
      LOCK -^a(1)#"D"  // Lock Table ModeCount: Exclusive
         WRITE "2nd unlock",! HANG 5
      LOCK -^a(1)#"D"  // Lock Table ModeCount: Exclusive->Delock
         WRITE "3rd unlock",! HANG 5
      TCOMMIT

    

      TSTART
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK +^a(1)      // Lock Table ModeCount: Exclusive
      LOCK -^a(1)#"I"  // Lock Table ModeCount: Exclusive/2
         WRITE "1st unlock",! HANG 5
      LOCK -^a(1)#"D"  // Lock Table ModeCount: Exclusive
         WRITE "2nd unlock",! HANG 5
      LOCK -^a(1)#"D"  // Lock Table ModeCount: null (immediate unlock)
         WRITE "3rd unlock",! HANG 5
      TCOMMIT

    

timeout

The number of seconds or fractions of a second to wait for a lock request to succeed before timing out. timeout is an optional argument. If omitted, the LOCK command waits indefinitely for a resource to be lockable; if the lock cannot be applied, the process will hang. The syntax for timeout is a mandatory colon (:), followed by an numeric value or an expression that evaluates to an numeric value.

Valid values are seconds with or without fractional tenths or hundredths of a second. Thus the following are all valid timeout values: :5, :5.5, :0.5, :.5, :0.05, :.05. Any value smaller than :0.01 is parsed as zero. A value of zero invokes one locking attempt before timing out. A negative number is equivalent to zero.

Commonly, a lock will wait if another process has a conflicting lock that prevents this lock request from acquiring (holding) the specified lock. The lock request waits until either a lock is released that resolves the conflict, or the lock request times out. Terminating the process also ends (deletes) pending lock requests. Lock conflict can result from many situations, not just one process requesting the same lock held by another process. A detailed explanation of lock conflict and lock request wait states is provided in the “Lock Management” chapter of Using ObjectScript.

If you use timeout and the lock is successful, InterSystems IRIS sets the $TEST special variable to 1 (TRUE). If the lock cannot be applied within the timeout period, InterSystems IRIS sets $TEST to 0 (FALSE). Issuing a lock request without a timeout has no effect on the current value of $TEST. Note that $TEST can also be set by the user, or by a JOB, OPEN, or READ timeout.

The following example applies a lock on lock name ^abc(1,1), and unlocks all prior locks held by the process:

  LOCK ^abc(1,1)

This command requests an exclusive lock: no other process can simultaneously hold a lock on this resource. If another process already holds a lock on this resource (exclusive or shared), this example must wait for that lock to be released. It can wait indefinitely, hanging the process. To avoid this, specifying a timeout value is strongly recommended:

  LOCK ^abc(1,1):10

If a LOCK specifies multiple lockname arguments in a comma-separated list, each lockname resource may have its own timeout (syntax without parentheses), or all of the specified lockname resources may share a single timeout (syntax with parentheses).

• Without Parentheses: each lockname argument can have its own timeout. InterSystems IRIS parses this as multiple independent LOCK commands, so the timeout of one lock argument does not affect the other lock arguments. Lock arguments are parsed in strict left-to-right order, with each lock request either completing or timing out before the next lock request is attempted.

• With Parentheses: all lockname arguments share a timeout. The LOCK must successfully apply all locks (or unlocks) within the timeout period. If the timeout period expires before all locks are successful, none of the lock operations specified in the LOCK command are performed, and control returns to the process.

InterSystems IRIS performs multiple operations in strict left-to-right order. Therefore, in LOCK syntax without parentheses, the $TEST value indicates the outcome of the last (rightmost) of multiple lockname lock requests.

In the following examples, the current process cannot lock ^a(1) because it is exclusively locked by another process. These examples use a timeout of 0, which means they make one attempt to apply the specified lock.

The first example locks ^x(1) and ^z(1). It sets $TEST=1 because ^z(1) succeeded before timing out:

  LOCK +^x(1):0,+^a(1):0,+^z(1):0

The second example locks ^x(1) and ^z(1). It sets $TEST=0 because ^a(1) timed out. ^z(1) did not specify a timeout and therefore had no effect on $TEST:

  LOCK +^x(1):0,+^a(1):0,+^z(1)

The third example applies no locks, because a list of locks in parentheses is an atomic (all-or-nothing) operation. It sets $TEST=0 because ^a(1) timed out:

  LOCK +(^x(1),^a(1),^z(1)):0

Automatic Unlock

When a process terminates, InterSystems IRIS performs an implicit argumentless LOCK to clear all locks that were applied by the process. It removes both held locks and lock wait requests.

Locks in a Network

In a networked system, one or more servers may be responsible for resolving locks on global variables.

You can use the LOCK command with any number of servers, up to 255.

You can use ^$LOCK to list remote locks, but it cannot list the lock state of a remote lock.

Remote locks held by a client job on a remote server system are released when you call the ^RESJOB utility to remove the client job.