Class Lock

  • A Lock is a mutual-exclusion lock used to ensure that only one instance of a script executes a given section of code at a time, particularly useful for callbacks and triggers to prevent collisions with shared resources.

  • TheLock class provides methods such ashasLock(),releaseLock(),tryLock(timeoutInMillis), andwaitLock(timeoutInMillis) to manage the lock's acquisition and release.

  • Using a lock, like in the provided example of generating unique ticket numbers, prevents issues where multiple users accessing shared properties simultaneously could lead to incorrect or duplicate data.

Lock

A representation of a mutual-exclusion lock.

This class lets scripts make sure that only one instance of the script executes a givensection of code at a time. This is particularly useful for callbacks and triggers, where a useraction might cause changes to a shared resource and you want to ensure that there aren'tcollisions.

The following example shows how to use a lock in a form submit handler.

// Generates a unique ticket number for every form submission.functiononFormSubmit(e){consttargetCell=e.range.offset(0,e.range.getNumColumns(),1,1);// Gets a script lock before modifying a shared resource.constlock=LockService.getScriptLock();// Waits for up to 30 seconds for other processes to finish.lock.waitLock(30000);constscriptProperties=PropertiesService.getScriptProperties();constticketNumber=Number(scriptProperties.getProperty('lastTicketNumber'))+1;scriptProperties.setProperty('lastTicketNumber',ticketNumber);// Releases the lock so that other processes can continue.lock.releaseLock();targetCell.setValue(ticketNumber);}
Without the Lock service, if two users submit the form at approximately the same time, the ticketnumbers could end up the same, since thelastTicketNumber property could change after itwas read from theScriptProperties but before the new value was written back.

Methods

MethodReturn typeBrief description
hasLock()BooleanReturns true if the lock was acquired.
releaseLock()voidReleases the lock, allowing other processes waiting on the lock to continue.
tryLock(timeoutInMillis)BooleanAttempts to acquire the lock, timing out after the provided number of milliseconds.
waitLock(timeoutInMillis)voidAttempts to acquire the lock, timing out with an exception after the provided number ofmilliseconds.

Detailed documentation

hasLock()

Returns true if the lock was acquired. This method will return false iftryLock(timeoutInMillis) orwaitLock(timeoutInMillis) were never called, timed out before the lock could be retrieved, or ifreleaseLock() was called.

constlock=LockService.getScriptLock();lock.tryLock(10000);if(!lock.hasLock()){Logger.log('Could not obtain lock after 10 seconds.');}

Return

Boolean — true if the lock was acquired, false otherwise

releaseLock()

Releases the lock, allowing other processes waiting on the lock to continue. The lock isautomatically released when the script terminates, but for efficiency it is best to release itas soon as you no longer need exclusive access to a section of code. This method has no effectif the lock has not been acquired.

Note that if you are working with a spreadsheet, you should call SpreadsheetApp.flush()prior to releasing the lock, to commit all pending changes to the spreadsheet while you stillhave exclusive access to it.

constlock=LockService.getScriptLock();lock.waitLock(10000);// Do some work on a shared resource.lock.releaseLock();

tryLock(timeoutInMillis)

Attempts to acquire the lock, timing out after the provided number of milliseconds. This methodhas no effect if the lock has already been acquired.

constlock=LockService.getScriptLock();constsuccess=lock.tryLock(10000);if(!success){Logger.log('Could not obtain lock after 10 seconds.');}

Parameters

NameTypeDescription
timeoutInMillisIntegerhow long to wait to acquire the lock, in milliseconds

Return

Boolean — true if the lock was acquired, false otherwise

waitLock(timeoutInMillis)

Attempts to acquire the lock, timing out with an exception after the provided number ofmilliseconds. This method is the same astryLock(timeoutInMillis) except that it throws an exceptionwhen the lock could not be acquired instead of returning false.

constlock=LockService.getScriptLock();try{lock.waitLock(10000);}catch(e){Logger.log('Could not obtain lock after 10 seconds.');}

Parameters

NameTypeDescription
timeoutInMillisIntegerhow long to wait to acquire the lock, in milliseconds

Throws

Error — if the method timed out before the lock was acquired

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-11 UTC.