xdmp.lockForUpdate( $uri as String ) as null
Acquires an intent exclusive transaction lock on a URI. If a shared transaction lock on the URI is already held by the current transaction it is promoted to an exclusive lock. If a shared or exclusive transaction lock on the URI is already held by some other transaction, this function blocks until that lock is released.
|$uri||The URI to be locked for update.|
This function allows an update transaction to acquire an exclusive write lock on a URI without specifying an update. Deadlocks and restarted transactions can be avoided by first explicitly acquiring an exclusive transaction lock on the URI with this function, before implicitly acquiring a shared transaction lock reading a document with that URI.
An exclusive transaction lock on a URI is automatically and implicitly acquired when an update function is applied on that URI. Similarly, a shared transaction lock on a URI is automatically and implicitly acquired when a document with that URI is read by an update transaction. If two update transactions concurrently read a document and then apply an update function on it, a deadlock can occur, because each transaction waits for the other to release its shared lock in order to escalate to an exclusive lock. This deadlock is automatically detected by the system, one of the transactions is restarted and its locks are released, and the other transaction proceeds.
Note that the lock acquired by this function is a relatively light transaction lock for database consistency, not a relatively heavy persistent document lock for file system emulation through WebDAV.