Class Lock

Bloquear

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

Essa classe permite que os scripts verifiquem se apenas uma instância do script executa uma determinada seção de código por vez. Isso é particularmente útil para callbacks e acionadores, 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) {
  var targetCell = e.range.offset(0, e.range.getNumColumns(), 1, 1);

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

  var 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 no mesmo horário, os números dos tíquetes poderão ser os mesmos, já que a propriedade lastTicketNumber poderá mudar depois de ser lida no ScriptProperties, mas antes de o novo valor ser gravado.

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 aguardem a continuidade dele.
tryLock(timeoutInMillis)	Boolean	Tenta conseguir o bloqueio, expirando após o número fornecido de milissegundos.
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 retornará falso se tryLock(timeoutInMillis) ou waitLock(timeoutInMillis) nunca tiverem sido chamados, se o tempo limite for atingido antes de o bloqueio ser recuperado ou se releaseLock() tiver sido chamado.

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

Retorno

Boolean: verdadeiro se o bloqueio tiver sido adquirido. Caso contrário, será falso.

---

releaseLock()

Libera o bloqueio, permitindo que outros processos aguardem a continuidade dele. O bloqueio é liberado automaticamente quando o script é encerrado, mas para aumentar a 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 SheetApp.clear() antes de liberar o bloqueio para confirmar todas as alterações pendentes na planilha enquanto ainda tiver acesso exclusivo a ela.

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

---

tryLock(timeoutInMillis)

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

var lock = LockService.getScriptLock();
var 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 até adquirir o bloqueio (milissegundos)

Retorno

Boolean: verdadeiro se o bloqueio tiver sido adquirido. Caso contrário, será falso.

---

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), mas gera uma exceção quando não é possível adquirir o bloqueio, em vez de retornar "false".

var 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 até adquirir o bloqueio (milissegundos)

Gera

Error: se o método expirou antes da aquisição do bloqueio.