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 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 handler 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 de tíquetes poderão ser iguais, já que a propriedade lastTicketNumber poderá mudar depois de ser lida de ScriptProperties, mas antes que o novo valor seja 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 que aguardam o bloqueio continuem.
tryLock(timeoutInMillis)	Boolean	Tenta adquirir o bloqueio, atingindo o tempo limite após o número de milissegundos fornecido.
waitLock(timeoutInMillis)	void	Tenta adquirir o bloqueio, atingindo o tempo limite com uma exceção após o número de milissegundos fornecido.

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, atingiram o tempo limite 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 aguardam o bloqueio continuem. O bloqueio é liberado automaticamente quando o script é encerrado, mas, para maior eficiência, é melhor liberá-lo assim que você não precisar mais de acesso exclusivo a uma seção de código. Esse método não tem efeito se o bloqueio não foi adquirido.

Se você estiver trabalhando com uma planilha, chame SpreadsheetApp.flush() antes de liberar o bloqueio para confirmar todas as mudanças pendentes na planilha enquanto ainda tiver 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, atingindo o tempo limite após o número de milissegundos fornecido. Esse método não tem efeito se o bloqueio já foi 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	Tempo de espera para adquirir o bloqueio, em milissegundos.

Retornar

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

---

waitLock(timeoutInMillis)

Tenta adquirir o bloqueio, atingindo o tempo limite com uma exceção após o número de milissegundos fornecido. 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	Tempo de espera para adquirir o bloqueio, em milissegundos.

Gera

Error — se o método atingiu o tempo limite antes que o bloqueio fosse adquirido