API блокировок веб-сайта

API блокировок веб-сайта позволяет скриптам, выполняющимся в одном окне вкладки или работнике, асинхронно получать блокировку, удерживать ее во время выполнения работы, а затем освободить ее. Пока блокировка удерживается, никакой другой скрипт, выполняющийся в том же источнике, не может получить ту же блокировку, что позволяет веб-приложению, работающему в нескольких вкладках или работниках, координировать работу и использование ресурсов.

Блокировка — это абстрактное понятие, представляющее некоторый потенциально общий ресурс, идентифицируемый именем, выбранным веб-приложением. Например, если веб-приложение, работающее в нескольких вкладках, хочет гарантировать, что только одна вкладка синхронизирует данные между сетью и Indexed DB, каждая вкладка может попытаться получить блокировку «my_net_db_sync», но только одна вкладка успешно получит блокировку (шаблон выбора лидера).

API используется следующим образом:

1. Блокировка запрашивается.
2. Работа выполняется с удержанием блокировки в асинхронной задаче.
3. Блокировка автоматически освобождается по завершении задачи.

navigator.locks.request("my_resource", async (lock) => {
  // The lock has been acquired.
  await do_something();
  await do_something_else();
  // Now the lock will be released.
});

Пока блокировка удерживается, запросы на ту же блокировку из текущего контекста выполнения или из других вкладок/работников будут помещены в очередь. Первый запрос в очереди будет удовлетворен только при освобождении блокировки.

API предоставляет необязательные функции, которые могут использоваться по мере необходимости, включая:

• возвращение значений из асинхронной задачи
• режимы блокировки: общая и эксклюзивная
• условный захват
• диагностика для запроса состояния блокировок в источнике
• обходной путь для защиты от тупиков

Блокировки ограничены источниками; блокировки, полученные вкладкой из https://example.com не влияют на блокировки, полученные вкладкой из https://example.org:8080, так как это отдельные источники.

Основной точкой входа является navigator.locks.request(), который запрашивает блокировку. Он принимает имя блокировки, необязательный набор параметров и обратный вызов. Обратный вызов вызывается, когда блокировка предоставлена. Блокировка автоматически освобождается, когда обратный вызов возвращается, поэтому обычно обратный вызов является асинхронной функцией, что приводит к освобождению блокировки только при полном завершении асинхронной функции.

Сам метод request() возвращает промис, который разрешается, когда блокировка освобождена; внутри асинхронной функции скрипт может await вызов, чтобы сделать поток асинхронного кода линейным. Например:

await do_something_without_lock();

// Request the lock.
await navigator.locks.request("my_resource", async (lock) => {
  // The lock has been acquired.
  await do_something_with_lock();
  await do_something_else_with_lock();
  // Now the lock will be released.
});
// The lock has been released.

await do_something_else_without_lock();

При запросе блокировки можно передать несколько параметров:

• mode: По умолчанию режим — «эксклюзивный», но можно указать «общий». Только один «эксклюзивный» держатель блокировки может иметь блокировку, но сразу могут быть удовлетворены несколько запросов «общего» типа. Это может быть использовано для реализации шаблона читатель-запись.
• ifAvailable: Если указано, запрос блокировки будет отклонен, если блокировку нельзя предоставить немедленно без ожидания. Обратный вызов вызывается с null.
• steal: Если указано, любые удерживаемые блокировки с тем же именем будут освобождены, и запрос будет удовлетворён, опережая любые запросы в очереди на него.
• signal: Можно передать AbortSignal, что позволяет прервать запрос на блокировку. Это можно использовать для реализации таймаута запросов.

Скрипты могут использовать метод navigator.locks.query() для анализа состояния менеджера блокировок для источника. Это может быть полезно при отладке, например, для определения причины невозможности получения блокировки. Результаты представляют собой моментальный снимок состояния менеджера блокировок, который идентифицирует удерживаемые и запрошенные блокировки и некоторые дополнительные данные (например, режим) о каждой из них в момент создания снимка.

В более сложных случаях, таких как удержание блокировки в течение произвольного промежутка времени, обратный вызов может возвращать промис, явно разрешенный скриптом:

// Capture promise control functions:
const { promise, resolve, reject } = Promise.withResolvers();

// Request the lock:
navigator.locks.request(
  "my_resource",
  // Lock is acquired.
  (lock) => promise, // Now lock will be held until either resolve() or reject() is called.
);

Тупик возникает, когда процесс больше не может продолжать работу, потому что каждая его часть ожидает запроса, который невозможно удовлетворить. Это может произойти с этим API в сложных случаях использования, например, если несколько блокировок запрашиваются в неправильном порядке. Если вкладка 1 удерживает блокировку А, а вкладка 2 удерживает блокировку Б, а затем вкладка 1 пытается получить блокировку Б, а вкладка 2 пытается получить блокировку А, ни один запрос не может быть удовлетворен. Веб-приложения могут избежать этого, используя различные стратегии, такие как обеспечение того, чтобы запросы на блокировку не были вложенными, или всегда были упорядоченными, или имели таймауты. Обратите внимание, что такие тупики влияют только на сами блокировки и код, зависящий от них; браузер, другие вкладки и другие скрипты на странице не затрагиваются.

Lock

Предоставляет имя и режим ранее запрошенной блокировки, которая получена в обратном вызове LockManager.request().

LockManager

Предоставляет методы для запроса нового объекта Lock и запроса существующего объекта Lock. Чтобы получить экземпляр LockManager, вызовите navigator.locks.

Navigator.locks Только чтение

Возвращает объект LockManager, который предоставляет методы для запроса нового объекта Lock и запроса существующего объекта Lock.

WorkerNavigator.locks Только чтение

Возвращает объект LockManager, который предоставляет методы для запроса нового объекта Lock и запроса существующего объекта Lock.