Class Lock

Bloquear

Uma representação de um bloqueio de exclusão mútua.

Essa classe permite que os scripts garantam que apenas uma instância do script execute uma determinada seção de código por vez. Isso é particularmente útil para callbacks e triggers, em que uma ação do usuário pode causar mudanças em um recurso compartilhado e você quer garantir que não haja colisões.

O exemplo a seguir mostra como usar um bloqueio em um gerenciador de envio de formulário.

// Generates a unique ticket number for every form submission.
function onFormSubmit(e) {
  const targetCell = e.range.offset(0, e.range.getNumColumns(), 1, 1);

  // Gets a script lock before modifying a shared resource.
  const lock = LockService.getScriptLock();
  // Waits for up to 30 seconds for other processes to finish.
  lock.waitLock(30000);

  const scriptProperties = PropertiesService.getScriptProperties();

  const ticketNumber =
      Number(scriptProperties.getProperty('lastTicketNumber')) + 1;
  scriptProperties.setProperty('lastTicketNumber', ticketNumber);

  // Releases the lock so that other processes can continue.
  lock.releaseLock();

  targetCell.setValue(ticketNumber);
}

Sem o serviço de bloqueio, se dois usuários enviarem o formulário aproximadamente ao mesmo tempo, os números dos tíquetes poderão ser iguais, já que a propriedade lastTicketNumber pode mudar depois de ser lida do ScriptProperties, mas antes que o novo valor seja gravado novamente.

Métodos

Método	Tipo de retorno	Breve descrição
hasLock()	Boolean	Retorna true se o bloqueio foi adquirido.
releaseLock()	void	Libera o bloqueio, permitindo que outros processos que estão aguardando continuem.
tryLock(timeoutInMillis)	Boolean	Tenta adquirir o bloqueio, expirando após o número de milissegundos fornecido.
waitLock(timeoutInMillis)	void	Tenta adquirir o bloqueio, expirando com uma exceção após o número fornecido de milissegundos.

Documentação detalhada

hasLock()

Retorna true se o bloqueio foi adquirido. Esse método retorna false se tryLock(timeoutInMillis) ou waitLock(timeoutInMillis) nunca foram chamados, se o tempo limite expirou antes que o bloqueio pudesse ser recuperado ou se releaseLock() foi chamado.

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

Retornar

Boolean: true se o bloqueio foi adquirido, false caso contrário.

---

releaseLock()

Libera o bloqueio, permitindo que outros processos que estão aguardando continuem. O bloqueio é liberado automaticamente quando o script termina, mas, para eficiência, é melhor liberá-lo assim que você não precisar mais de acesso exclusivo a uma seção do código. Esse método não terá efeito se o bloqueio não tiver sido adquirido.

Se você estiver trabalhando com uma planilha, chame SpreadsheetApp.flush() antes de liberar o bloqueio para confirmar todas as mudanças pendentes enquanto ainda tem acesso exclusivo a ela.

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

---

tryLock(timeoutInMillis)

Tenta adquirir o bloqueio, expirando após o número de milissegundos fornecido. Esse método não tem efeito se o bloqueio já tiver sido adquirido.

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

Parâmetros

Nome	Tipo	Descrição
timeoutInMillis	Integer	Quanto tempo esperar para adquirir o bloqueio, em milissegundos.

Retornar

Boolean: true se o bloqueio foi adquirido, false caso contrário.

---

waitLock(timeoutInMillis)

Tenta adquirir o bloqueio, expirando com uma exceção após o número fornecido de milissegundos. Esse método é igual a tryLock(timeoutInMillis), exceto que ele gera uma exceção quando o bloqueio não pode ser adquirido, em vez de retornar false.

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

Parâmetros

Nome	Tipo	Descrição
timeoutInMillis	Integer	Quanto tempo esperar para adquirir o bloqueio, em milissegundos.

Gera

Error: se o método atingir o tempo limite antes da aquisição do bloqueio