Locking and Concurrency Control

One of the arguments for a lock command is the lock name. Lock names are arbitrary, but by universal convention, programmers use names identical to the items they lock. Usually, the item to be locked is a global or a node of a global. Lock names typically follow the same naming conventions as local and global variables, including case sensitivity and the use of subscripts. Find out more in Variables.

Competing processes need to use the same lock name when accessing shared data. In InterSystems IRIS, locking is not enforced at the data level; it is enforced by agreement between processes that use the same lock name. If two processes use different lock names for the same global or data structure, they can both acquire locks independently and modify the same data without coordination. To prevent conflicts, establish clear naming conventions for locks and apply them consistently across all code that accesses shared data. Lock names should be meaningful and clearly identify the global or node being locked.

Timeouts specify the duration a process should wait for a lock request to succeed before timing out. If a lock cannot be applied within the specified timeout period, the process will stop waiting, and the lock request will fail. Timeouts are especially relevant to incremental locks to avoid deadlocks.

A timeout does the following:

1. Attempts to add the given lock to the lock table. The lock is added to the lock queue, if one exists.

2. Pauses execution until the lock is acquired or the timeout period ends, whichever comes first.

3. For ObjectScript LOCK: Sets the value of the $TEST special variable. If the lock is acquired, InterSystems IRIS sets $TEST equal to 1. Otherwise, InterSystems IRIS sets $TEST equal to 0.

   For Python iris.lock(): Raises IRISTimeoutError if the timeout period elapses before the lock is acquired; otherwise, returns normally.

See Creating Locks with Timeouts for examples and more.

A lock can be acquired in two basic modes: incremental or simple. These modes control how a process manages existing locks when acquiring new ones.

Incremental Locks

An incremental lock adds a new entry for the specified name without releasing any existing locks. Each acquisition increments a reference count. The lock is only released when the count decrements to zero, preventing other processes from acquiring it until then.

Note:

By default, all Python locks are incremental.

Python ObjectScript

# Exclusive, non-escalating lock, no wait
iris.lock("", 0, "^MyGlobal", 1)

LOCK +^MyGlobal(1)

Incremental locks are the standard way to protect critical sections because they let you hold multiple locks at once, and acquire them at different times during execution. They are best combined with timeouts to avoid deadlocks.

Simple Locks

In ObjectScript, simple locks are atomic replacements of the held set; they're rarely used outside small critical sections or legacy code. A simple lock replaces all existing locks held by the process with the new one(s). Unlike incremental locks, it does not maintain a reference count across acquisitions.

ObjectScript

LOCK (^MyVar1,^MyVar2,^MyVar3)

Simple locks are less common because applications usually need to acquire multiple locks at different stages of processing. However, you may specify lock types and timeouts with simple locks.

Note:

Simple locks are ObjectScript only. They cannot be used in Python.

InterSystems IRIS maintains a system-wide, in-memory table that records all current locks and the processes that own them. This table, the lock table, is accessible via the Management Portal (System Operation > Locks > Manage Locks), where you can view the locks and (in rare cases, if needed) remove them. Note that a given process can own multiple locks with different names (or even multiple locks with the same name).

When a process ends, the system automatically releases all locks it owns. Thus, it is not generally necessary to remove locks via the Management Portal, except in cases of an application errors.

Lock Table Full

If the lock table reaches capacity, InterSystems IRIS writes the following message to the messages.log file:

LOCK TABLE FULL

Filling the lock table is not generally considered to be an application error; InterSystems IRIS also provides a lock queue, and processes wait until there is space to add their locks to the lock table.

To assign a lock type:

Python ObjectScript

 iris.lock(lock_mode, timeout, ^+lockReference, subscripts)

 LOCK +lockname#locktype

Where lock_mode or Locktype is one or more lock type codes, in any order, enclosed in double quotes for addition (or removal). In ObjectScript, a pound character (#) must separate the lock name from the lock type.

Any lock is either exclusive (the default) or shared (S). These types have the following significance:

• While one process owns an exclusive lock (with a given lock name), no other process can acquire any lock with that lock name.

• While one process owns a shared lock (with a given lock name), other processes can acquire shared locks with that name, but no process can acquire an exclusive lock with that name.

The typical purpose of an exclusive lock is to indicate that you intend to modify a value and that other processes should not attempt to read or modify that value until you are done. The typical purpose of a shared lock is to indicate that you intend to read a value and that other processes should not attempt to modify that value; they can, however, read the value.

For a detailed example, see Example: Protecting Application Data.

Any lock is either non-escalating (the default) or escalating (E). These types determine how InterSystems IRIS manages memory and lock tracking when your application holds many locks on related nodes. They have the following significance:

• For non-escalating locks, each node you lock is tracked individually in the lock table. This gives precise control, but can consume memory if you lock many nodes.

• For escalating locks, when a process locks more than a specific number (by default, 1,000) of parallel nodes at the same subscript level, InterSystems IRIS automatically “escalates” them. It replaces the individual node locks with a single lock on the parent node, implicitly locking the entire branch. Releasing child node locks decrements the count. When enough locks are removed, InterSystems IRIS automatically removes the parent-level lock.

The typical purpose of an escalating lock is to manage large numbers of locks without overwhelming the lock table. By contrast, use non-escalating locks when fine-grained concurrency and memory usage are not a concern.

For a detailed example, see Example: Escalating Lock.

The lock type codes I (immediate) and D (deferred) control when a lock is released relative to transactions. These options adjust unlock timing only; they do not change the lock name or mode. They are not case-sensitive and cannot be used together for the same lock operation.

• Immediate unlock releases the lock as soon as the unlock is issued, regardless of whether a transaction is active. Use when exclusive access is no longer required, but the transaction continues for other work.

• Deferred unlock schedules the unlock to occur at the end of the current transaction (commit or rollback). Use to keep the resource protected until the transaction reaches a durability boundary.

For syntax, see Assigning Lock Types. For end-to-end demonstrations, see Example: Immediate Unlock and Example: Deferred Unlock. Related timing behavior is shown in Example: Timed Lock.

To add a lock, use a lock command as follows:

Python ObjectScript

iris.lock(lockMode, timeout, lockReference, *subscripts)

 LOCK +lockname#locktype :timeout

There are different types of locks, each with distinct behaviors. With lock_mode or #locktype, you can specify the lock variation. Learn more about the lock types available in Lock Types.

In the above example, you can specify a timeout, where timeout is the timeout period in seconds. If you specify a timeout, this lock becomes an Incremental Lock with a Timeout. A timeout is an effective way to reduce the risk of deadlock. If you specify timeout as 0, InterSystems IRIS makes a single attempt to add the lock. In Python, a lock attempt that times out raises IRISTimeoutError; in ObjectScript, $TEST is set to 0.

Unlocking All Locks

To remove all locks held by the current process:

Python ObjectScript

 iris.releaseAllLocks() 

 LOCK 

For both Python and ObjectScript, these contain no arguments.

Unlocking all locks is not common practice. It is best to release specific locks as soon as possible. Locks are automatically released when their related process ends. Avoid using this in shared processes or servers, as it can remove unrelated locks held by helpers within the same process.

Removing Typed Locks

To remove a lock of a specific type:

Python ObjectScript

iris.unlock(lock_list, timeout_value=None, locktype=None)

 LOCK -lockname#locktype 

Examples:

Python ObjectScript

# Remove one shared lock on ^G(1)
iris.unlock(['^G(1)'], None, "S")

# Remove one escalating lock on ^G(1)
iris.unlock(['^G(1)'], None, "E")

# Remove one exclusive, non-escalating lock on ^G(1)
iris.unlock(['^G(1)'])

 LOCK -^G(1)#"S"   ; removes one shared lock
 LOCK -^G(1)#"E"   ; removes one exclusive escalating lock
 LOCK -^G(1)#"SD"  ; removes one shared lock with deferred unlock

An incremental lock allows you to apply the same lock multiple times, effectively incrementing the lock count. By default, all locks made in Python are incremental.

To add an incremental lock:

Python ObjectScript

 # Python locks are always incremental; here with 0-second timeout (nonblocking)
iris.lock("", 0, "^Customer", 1234)

 LOCK +lockname

A process can add multiple incremental locks with the same name; these locks can be of different types or the same type. Learn more about lock types in Lock Types.

To learn more about incremental locks, see Incremental Locks.

Timeouts specify the duration a process should wait for a lock request to succeed before timing out.

The following are examples of incremental locks with timeouts:

Python ObjectScript

iris.lock(lock_mode, timeout, ^+lockReference, subscripts)

 LOCK +lockname#locktype :timeout

Where timeout or :timeout is the timeout period in seconds. In ObjectScript, the space before the colon is optional. If you specify a timeout as 0, InterSystems IRIS will attempt to add a lock.

If you're using a timeout argument, you may be advised to build in a check for the value of the $TEST; in Python, wrap iris.lock() in a “try/except” block and catch IRISTimeoutError if the lock cannot be acquired in time. The following shows an example:

Python ObjectScript

try:
    # Try up to 2 seconds to acquire an exclusive, non-escalating lock
    iris.lock("", 2, "^ROUTINE", routinename)
    # ... protected work ...
finally:
    # Release using the same name
    iris.unlock([f'^ROUTINE("{routinename}")'])

 Lock +^ROUTINE(routinename):0 
 If '$TEST {  Return $$$ERROR("Cannot lock the routine: ",routinename)}

While one process holds an exclusive lock with a given lock name, no other process can acquire a lock with that name.

If the lock name starts with a caret, this rule applies to all namespaces that use the same globals database as the locked process.

For example, suppose the namespaces ALPHA and BETA are both configured to use database GAMMA as their globals database. The following shows a sketch:

Then consider the following scenario:

1. In namespace ALPHA, process A acquires an exclusive lock named ^MyGlobal(15).

2. In namespace BETA, process B tries to acquire a lock with the name ^MyGlobal(15). This lock command does not return; the process is blocked until process A releases the lock.

In this scenario, the lock table contains only the entry for the lock owned by process A. If you examine the lock table, you will notice that the Directory column indicates the database to which this lock applies. For example:

If one or more namespaces have global mappings, InterSystems IRIS automatically enforces the lock mechanism across all applicable namespaces. The system automatically creates additional lock table entries when locks are acquired in the non-default namespace.

For example, suppose that namespace ALPHA is configured to use database ALPHADB as its globals database. Suppose that namespace BETA is configured to use a different database (BETADB) as its globals database. Namespace BETA also includes a global mapping that specifies that ^MyGlobal is stored in the ALPHADB database. The following shows a sketch:

Then consider the following scenario:

1. In namespace ALPHA, process A acquires an exclusive lock with the name ^MyGlobal(15).

   The lock table contains only the entry for the lock owned by process A. This lock applies to the ALPHADB database:

   

2. In namespace BETA, process B tries to acquire a lock with the name ^MyGlobal(15). The lock command does not return; the process is blocked until process A releases the lock.

Example: Namespace Uses a Mapped Global Subscript

If one or more namespaces have global mappings that use subscript level mappings, InterSystems IRIS automatically enforces the lock mechanism across all applicable namespaces. The system automatically creates additional lock table entries when locks are acquired in a non-default namespace.

For example, suppose that namespace ALPHA is configured to use the database ALPHADB as its globals database. Namespace BETA uses the BETADB database as its globals database.

Also suppose that the namespace BETA also includes a subscript-level global mapping so that ^MyGlobal(15) is stored in the ALPHADB database (while the rest of this global is stored in the namespace's default location). The following shows a sketch:

Then consider the following scenario:

1. In namespace ALPHA, process A acquires an exclusive lock with the name ^MyGlobal(15).

   As with the previous scenario, the lock table contains only the entry for the lock owned by Process A. This lock applies to the ALPHADB database (for example, c:\InterSystems\IRIS\mgr\alphadb).

2. In namespace BETA, process B tries to acquire a lock named ^MyGlobal(15). This lock command does not return; the process is blocked until process A releases the lock.

When a non-default namespace acquires a lock, the overall behavior remains the same; however, InterSystems IRIS handles the details slightly differently. Suppose that in namespace BETA, a process acquires a lock with the name ^MyGlobal(15). In this case, the lock table contains two entries, one for the ALPHADB database and one for the BETADB database. The process in the BETA namespace owns both locks. Releasing the name in BETA removes both entries automatically.

When this process releases the lock name ^MyGlobal(15), the system automatically removes both locks.

Code running in one namespace can use an extended reference to access a global that is not otherwise available in that namespace. In this case, InterSystems IRIS adds an entry to the lock table that affects the relevant database. The lock is owned by the process that created it. For example, consider the following scenario. For simplicity, there are no global mappings in this scenario.

1. Process A is running in the ALPHA namespace, and this process uses the following command to acquire a lock on a global that is available in the BETA namespace:

   Python ObjectScript

   # Lock ^["beta"]MyGlobal(15) from the current namespace
   iris.lock("", 0, '^["beta"]MyGlobal', 15)
   
   

   

    lock ^["beta"]MyGlobal(15)

   

2. Now the lock table includes the following entry:

   

   Note that this shows only the global name (rather than the reference used to access it). Also, in this scenario, BETADB is the default database for the BETA namespace.

3. In namespace BETA, process B tries to acquire a lock with the name ^MyGlobal(15). This lock command does not return; the process is blocked until process A releases the lock.

A process-private global is technically an extended reference, but InterSystems IRIS does not support using a process-private global name as a lock name; you would not need such a lock anyway because, by definition, only one process can access such a global.