<pre class=metadata>
Title: Web Locks API
Shortname: WebLocks
Abstract: This document defines a web platform API that allows script to asynchronously acquire a lock over a resource, hold it while work is performed, then release it. While held, no other script in the origin can acquire a lock over the same resource. This allows contexts (windows, workers) within a web application to coordinate the usage of resources.
Status: CG-DRAFT
ED: https://wicg.github.io/web-locks/
Level: 1
Editor: Joshua Bell, Google Inc. https://google.com, jsbell@google.com
Group: WICG
Test Suite: https://github.com/web-platform-tests/wpt/tree/master/web-locks
Favicon: logo-lock.png
Complain About: accidental-2119 yes, missing-example-ids yes
Markup Shorthands: css no, markdown yes
</pre>

<pre class=anchors>
spec: ecma262; urlPrefix: https://tc39.github.io/ecma262/
    type: dfn
        text: agent; url: agent
spec: html; urlPrefix: https://html.spec.whatwg.org/multipage/
    urlPrefix: webstorage.html
        type: dfn
            text: localStorage; url: dom-localstorage
    urlPrefix: webappapis.html
        type: dfn
            text: agent cluster; url: integration-with-the-javascript-agent-cluster-formalism
</pre>

<pre class=link-defaults>
spec:infra; type:dfn; text:list
spec:html; type:dfn; for:/; text:origin
spec:html; type:dfn; for:/; text:browsing context
spec:webidl; type:dfn; text:resolve
</pre>

<style>
dl.domintro dt {
    font-family: Menlo, Consolas, "DejaVu Sans Mono", Monaco, monospace;

    padding-top: 0.5em;
    padding-bottom: 1em;
}
dl.domintro dt a {
    color: inherit; border-bottom-style: none;
}
dl.domintro dt code {
    font-size: inherit;
}
</style>

<img src="logo-lock.svg" alt="logo"
    style="height: 100px; width: 100px; position: absolute; right: 20px; top: 30px;">


<!-- ====================================================================== -->
# Introduction # {#introduction}
<!-- ====================================================================== -->

*This section is non-normative.*

A [=lock request=] is made by script for a particular [=resource name=] and [=/mode=]. A scheduling algorithm looks at the state of current and previous requests, and eventually grants a lock request. A [=lock-concept|lock=] is a granted request; it has a [=resource name=] and [=/mode=]. It is represented as an object returned to script. As long as the lock is held it may prevent other lock requests from being granted (depending on the name and mode). A lock can be released by script, at which point it may allow other lock requests to be granted.

The API provides optional functionality that may be used as needed, including:

* returning values from the asynchronous task,
* shared and exclusive lock modes,
* conditional acquisition,
* diagnostics to query the state of locks in an origin, and
* an escape hatch to protect against deadlocks.

Cooperative coordination takes place within the scope of same-origin [=/agents=]; this may span multiple [=/agent clusters=].

<aside class=note>
[=/Agents=] roughly correspond to windows (tabs), iframes, and workers. [=/Agent clusters=] correspond to independent processes in some user agent implementations.
</aside>

<!-- ====================================================================== -->
## Usage Overview ## {#usage-overview}
<!-- ====================================================================== -->

The API is used as follows:

1. The lock is requested.
1. Work is done while holding the lock in an asynchronous task.
1. The lock is automatically released when the task completes.

<aside class=example id=example-basic-usage>

A basic example of the API usage is as follows:

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

Within an asynchronous function, the request itself can be awaited:

```js
// Before requesting the lock.
await navigator.locks.request('my_resource', async lock => {
   // The lock has been acquired.
   await do_something();
   // Now the lock will be released.
});
// After the lock has been released
```

</aside>

<!-- ====================================================================== -->
## Motivating Use Cases ## {#motivations}
<!-- ====================================================================== -->

A web-based document editor stores state in memory for fast access and persists changes (as a series of records) to a storage API such as the [[IndexedDB-2|Indexed Database API]] for resiliency and offline use, and to a server for cross-device use. When the same document is opened for editing in two tabs the work must be coordinated across tabs, such as allowing only one tab to make changes to or synchronize the document at a time. This requires the tabs to coordinate on which will be actively making changes (and synchronizing the in-memory state with the storage API), knowing when the active tab goes away (navigated, closed, crashed) so that another tab can become active.

In a data synchronization service, a "master tab" is designated. This tab is the only one that should be performing some operations (e.g. network sync, cleaning up queued data, etc). It holds a lock and never releases it. Other tabs can attempt to acquire the lock, and such attempts will be queued. If the "master tab" crashes or is closed then one of the other tabs will get the lock and become the new master.

The [[IndexedDB-2|Indexed Database API]] defines a transaction model allowing shared read and exclusive write access across multiple named storage partitions within an origin. Exposing this concept as a primitive allows any Web Platform activity to be scheduled based on resource availability, for example allowing transactions to be composed for other storage types (such as Caches [[Service-Workers]]), across storage types, even across non-storage APIs (e.g. network fetches).


<!-- ====================================================================== -->
# Concepts # {#concepts}
<!-- ====================================================================== -->

For the purposes of this specification:

 * Separate user profiles within a browser are considered separate user agents.
 * Every [private mode](https://github.com/w3ctag/private-mode) browsing session is considered a separate user agent.

A user agent has a <dfn>lock task queue</dfn> which is the result of [=starting a new parallel queue=].

The [=task source=] for [=enqueue steps|steps enqueued=] below is the <dfn export>web locks tasks source</dfn>.


<!-- ====================================================================== -->
## Resources Names ## {#resource-names}
<!-- ====================================================================== -->

A <dfn>resource name</dfn> is a [=JavaScript string=] chosen by the web application to represent an abstract resource.

A resource name has no external meaning beyond the scheduling algorithm, but is global
across [=browsing contexts=] within an [=/origin=]. Web applications are free to use any resource naming scheme.

<aside class=example id=example-indexeddb-transactions>
To mimic transaction locking over named stores within a named
database in [[IndexedDB-2]], an origin might compose resource names as:
```js
encodeURIComponent(db_name) + '/' + encodeURIComponent(store_name)
```
</aside>

Resource names starting with U+002D HYPHEN-MINUS (-) are reserved; requesting these will cause an exception.

<!-- ====================================================================== -->
## Lock Managers ## {#lock-managers}
<!-- ====================================================================== -->

A user agent has a <dfn>lock manager</dfn> for each [=/origin=], which encapsulates the state of all [=lock-concept|locks=] and [=lock requests=] for that origin.

Pages and workers ([=/agents=]) on a single [=/origin=] opened in the same user agent share a lock manager even if they are in unrelated [=browsing contexts=].

<aside class=note>

    There is an equivalence between the following:

    * Agents that share a [=lock manager=].
    * Agents that share a [=site storage unit=], i.e. a per-origin [=localStorage|local storage area=] [[HTML]], set of [[IndexedDB-2#database-construct|databases]] [[IndexedDB-2]], or [[Service-Workers#cache-objects|caches]] [[Service-Workers]].

</aside>

<aside class=issue>
Migrate this definition to [[HTML]] or [[Storage]] so it can be referenced by other standards.
</aside>


<!-- ====================================================================== -->
## Modes and Scheduling ## {#modes-scheduling}
<!-- ====================================================================== -->

A <dfn>mode</dfn> is either "{{exclusive}}" or "{{shared}}". Modes can be used to model the common [readers-writer lock](http://en.wikipedia.org/wiki/Readers%E2%80%93writer_lock) pattern. If an "{{exclusive}}" lock is held, then no other locks with that name can be granted. If a "{{shared}}" lock is held, other "{{shared}}" locks with that name can be granted &mdash; but not any "{{exclusive}}" locks. The default mode in the API is "{{exclusive}}".

Additional properties may influence scheduling, such as timeouts, fairness, and so on.


<!-- ====================================================================== -->
## Locks ## {#concept-lock}
<!-- ====================================================================== -->

A <dfn lt=lock-concept>lock</dfn> represents exclusive access to a shared resource.

<div dfn-for=lock-concept>

A [=lock-concept|lock=] has an <dfn>agent</dfn> which is an [=/agent=].

A [=lock-concept|lock=] has a <dfn>clientId</dfn> which is an opaque string.

A [=lock-concept|lock=] has an <dfn>origin</dfn> which is an [=/origin=].

A [=lock-concept|lock=] has a <dfn>name</dfn> which is a [=resource name=].

A [=lock-concept|lock=] has a <dfn>mode</dfn> which is one of "{{exclusive}}" or "{{shared}}".

A [=lock-concept|lock=] has a <dfn>waiting promise</dfn> which is a Promise.

A [=lock-concept|lock=] has a <dfn>released promise</dfn> which is a Promise.

<aside class=note>
There are two promises associated with a lock's lifecycle:

* A promise provided either implicitly or explicitly by the callback when the lock is granted which determines how long the lock is held. When this promise settles, the lock is released. This is known as the lock's [=lock-concept/waiting promise=].
* A promise returned by {{LockManager}}'s {{LockManager/request(name, callback)|request()}} method that settles when the lock is released or the request is aborted. This is known as the lock's [=lock-concept/released promise=].

```js
const p1 = navigator.locks.request('resource', lock => {
  const p2 = new Promise(r => {
    // Logic to use lock and resolve promise...
  });
  return p2;
});
```

In the above example, `p1` is the [=lock-concept/released promise=] and `p2` is the [=lock-concept/waiting promise=].
Note that in most code the callback would be implemented as an `async` function and the returned promise would be implicit, as in the following example:

```js
const p1 = navigator.locks.request('resource', async lock => {
  // Logic to use lock...
});
```

The [=lock-concept/waiting promise=] is not named in the above code, but is still present as the return value from the anonymous `async` callback.
Further note that if the callback is not `async` and returns a non-promise, the return value is wrapped in a promise that is immediately resolved; the lock will be released in an upcoming microtask, and the [=lock-concept/released promise=] will also resolve in a subsequent microtask.
</aside>

Each origin has a <dfn>held lock set</dfn> which is a [=/set=] of [=lock-concept|locks=].

When [=lock-concept|lock=] |lock|'s [=lock-concept/waiting promise=] settles (fulfills or rejects), [=enqueue the following steps=] on the [=lock task queue=]:

1. [=Release the lock=] |lock|.
1. [=Resolve=] |lock|'s [=lock-concept/released promise=] with |lock|'s [=lock-concept/waiting promise=].

</div>

<!-- ====================================================================== -->
## Lock Requests ## {#concept-lock-request}
<!-- ====================================================================== -->

A <dfn>lock request</dfn> represents a pending request for a [=lock-concept|lock=].

<div dfn-for="lock request">

A [=lock request=] is a tuple of (<dfn>agent</dfn>, <dfn>clientId</dfn>, <dfn>origin</dfn>, <dfn>name</dfn>, <dfn>mode</dfn>, <dfn>promise</dfn>).

A <dfn>lock request queue</dfn> is a [=queue=] of [=lock requests=].

Each origin has a <dfn>lock request queue map</dfn>, which is a [=map=] of [=resource names=] to [=lock request queues=].

A [=lock request=] |request| is said to be <dfn>grantable</dfn> if the following steps return true:

1. Let |origin| be |request|'s [=lock request/origin=].
1. Let |queueMap| be |origin|'s [=lock request queue map=].
1. Let |name| be |request|'s [=lock request/name=].
1. Let |queue| be |queueMap|[|name|].
1. Let |held| be |origin|'s [=held lock set=]
1. Let |mode| be |request|'s [=lock request/mode=]
1. If |mode| is "{{exclusive}}", then return true if all of the following conditions are true, and false otherwise:
    * No [=lock-concept|lock=] in |held| has a [=lock-concept/name=] that equals |name|
    * No [=lock request=] in |queue| earlier than |request| exists.
1. Otherwise, mode is "{{shared}}"; return true if all of the following conditions are true, and false otherwise:
    * No [=lock-concept|lock=] in |held| has [=lock-concept/mode=] "{{exclusive}}" and has a [=lock-concept/name=] that equals |name|.
    * No [=lock request=] in |queue| earlier than |request| exists.

</div>

<!-- ====================================================================== -->
## Agent Integration ## {#agent-integration}
<!-- ====================================================================== -->

<div class=algorithm>
When an [=/agent=] terminates, [=enqueue the following steps=] on the [=lock task queue=]:

<aside class=issue>
    Normative reference for <i>terminates</i>.
</aside>


1. For each [=lock request=] |request| with [=lock request/agent=] equal to the terminating agent:
    1. [=Abort the request=] |request|.
1. For each [=lock-concept|lock=] |lock| with [=lock-concept/agent=] equal to the terminating agent:
    1. [=Release the lock=] |lock|.

</div>

<!-- ====================================================================== -->
# API # {#api}
<!-- ====================================================================== -->

<!-- ====================================================================== -->
## Navigator Mixins ## {#navigator-mixins}
<!-- ====================================================================== -->

<xmp class=idl>
[SecureContext]
interface mixin NavigatorLocks {
  readonly attribute LockManager locks;
};
Navigator includes NavigatorLocks;
WorkerNavigator includes NavigatorLocks;
</xmp>

Each [=environment settings object=] has a {{LockManager}} object.

The {{NavigatorLocks/locks}} attribute's getter must return the [=context object=]'s [=relevant settings object=]'s {{LockManager}} object.

<!-- ====================================================================== -->
## {{LockManager}} class ## {#api-lock-manager}
<!-- ====================================================================== -->

<xmp class=idl>
[SecureContext, Exposed=(Window,Worker)]
interface LockManager {
  Promise<any> request(DOMString name,
                       LockGrantedCallback callback);
  Promise<any> request(DOMString name,
                       LockOptions options,
                       LockGrantedCallback callback);

  Promise<LockManagerSnapshot> query();
};

callback LockGrantedCallback = Promise<any> (Lock? lock);

enum LockMode { "shared", "exclusive" };

dictionary LockOptions {
  LockMode mode = "exclusive";
  boolean ifAvailable = false;
  boolean steal = false;
  AbortSignal signal;
};

dictionary LockManagerSnapshot {
  sequence<LockInfo> held;
  sequence<LockInfo> pending;
};

dictionary LockInfo {
  DOMString name;
  LockMode mode;
  DOMString clientId;
};
</xmp>

A {{LockManager}} instance allows script to make [=lock requests=] and query
the state of the origin's [=lock manager=].

<!-- ====================================================================== -->
### The {{LockManager/request(name, callback)|request()}} method ### {#api-lock-manager-request}
<!-- ====================================================================== -->

<div class=note>
  <dl class=domintro>
    <dt><var>promise</var> = navigator . locks .
        {{LockManager/request(name, callback)|request}}(<var>name</var>, <var>callback</var>)</dt>
    <dt><var>promise</var> = navigator . locks .
        {{LockManager/request(name, options, callback)|request}}(<var>name</var>, <var>options</var>, <var>callback</var>)</dt>
    <dd>

    The {{LockManager/request(name, callback)|request()}} method is called to request a lock.

    The |name| (initial argument) is a [=resource name=] string.

    The |callback| (final argument) is a [=callback function=] invoked with the {{Lock}} when granted. This is specified by script, and is usually an `async` function. The lock is held until the callback function completes. If a non-async callback function is passed in, then it is automatically wrapped in a promise that resolves immediately, so the lock is only held for the duration of the synchronous callback.

    The returned |promise| resolves (or rejects) with the result of the callback after the lock is released, or rejects if the request is aborted.

    Example:
```js
try {
  const result = await navigator.locks.request('resource', async lock => {
    // The lock is held here.
    await do_something();
    await do_something_else();
    return "ok";
    // The lock will be released now.
  });
  // |result| has the return value of the callback.
} catch (ex) {
  // if the callback threw, it will be caught here.
}
```

    The lock will be released when the callback exits for any reason &mdash; either when the code returns, or if it throws.

    An |options| dictionary can be specified as a second argument; the |callback| argument is always last.
    </dd>

    <!-- ======================================== -->

    <dt><var>options</var> . mode</dt>
    <dd>

    The {{LockOptions/mode}} option can be "{{exclusive}}" (the default if not specified) or "{{shared}}".
    Multiple tabs/workers can hold a lock for the same resource in "{{shared}}" mode, but only one tab/worker can hold a lock for the resource in "{{exclusive}}" mode.

    The most common use for this is to allow multiple readers to access a resource simultaneously but prevent changes.
    Once reader locks are released a single exclusive writer can acquire the lock to make changes, followed by another exclusive writer or more shared readers.


```js
await navigator.locks.request('resource', {mode: 'shared'}, async lock => {
  // Lock is held here. Other contexts might also hold the lock in shared mode,
  // but no other contexts will hold the lock in exclusive mode.
});
```
    </dd>

    <!-- ======================================== -->

    <dt><var>options</var> . ifAvailable</dt>
    <dd>

    If the {{LockOptions/ifAvailable}} option is `true`, then the lock is only granted if it can be without additional waiting. Note that this is still not *synchronous*; in many user agents this will require cross-process communication to see if the lock can be granted. If the lock cannot be granted, the callback is invoked with `null`. (Since this is expected, the request is *not* rejected.)

```js
await navigator.locks.request('resource', {ifAvailable: true}, async lock => {
  if (!lock) {
    // Didn't get it. Maybe take appropriate action.
    return;
  }
  // Lock is held here.
});
```
    </dd>

    <!-- ======================================== -->

    <dt><var>options</var> . signal</dt>
    <dd>

    The {{LockOptions/signal}} option can be set to an {{AbortSignal}}. This allows aborting a lock request, for example if the request is not granted in a timely manner:

```js
const controller = new AbortController();
setTimeout(() => controller.abort(), 200); // Wait at most 200ms.

try {
  await navigator.locks.request(
    'resource', {signal: controller.signal}, async lock => {
      // Lock is held here.
  });
  // Done with lock here.
} catch (ex) {
  // |ex| will be a DOMException with error name "AbortError" if timer fired.
}
```

    If an abort is signalled before the lock is granted, then the request promise will reject with an {{AbortError}}.
    Once the lock has been granted, the signal is ignored.
    </dd>

    <!-- ======================================== -->

    <dt><var>options</var> . steal</dt>
    <dd>
    If the {{LockOptions/steal}} option is `true`, then any held locks for the resource will be released (and the [=released promise=] of such locks will resolve with {{AbortError}}), and the request will be granted, preempting any queued requests for it.

    If a web application detects an unrecoverable state &mdash; for example, some coordination point like a Service Worker determines that a tab holding a lock is no longer responding &mdash; then it can "steal" a lock using this option.

    </dd>
  </dl>
</div>

<aside class=advisement>
    Use the {{LockOptions/steal}} option with caution.
    When used, code previously holding a lock will now be executing without guarantees that it is the sole context with access to the resource.
    Similarly, the code that used the option has no guarantees that other contexts will not still be executing as if they have access to the abstract resource.
    It is intended for use by web applications that need to attempt recovery in the face of application and/or user-agent defects, where behavior is already unpredictable.
</aside>

<div class=algorithm>

The <dfn method for=LockManager>request(|name|, |callback|)</dfn> and
<dfn method for=LockManager>request(|name|, |options|, |callback|)</dfn> methods, when invoked, must run these steps:

1. If |options| was not passed, then let |options| be a new {{LockOptions}} dictionary with default members.
1. Let |environment| be [=context object=]'s [=relevant settings object=].
1. Let |origin| be |environment|'s [=/origin=].
1. If |origin| is an [=opaque origin=], then return [=a promise rejected with=] a "{{SecurityError}}" {{DOMException}}.
1. If |name| starts with U+002D HYPHEN-MINUS (-), then return [=a promise rejected with=] a "{{NotSupportedError}}" {{DOMException}}.
1. If both |options|' |steal| dictionary member and |options|' |ifAvailable| dictionary member are true, then return [=a promise rejected with=] a "{{NotSupportedError}}" {{DOMException}}.
1. If |options|' |steal| dictionary member is true and |options|' |mode| dictionary member is not "{{exclusive}}", then return [=a promise rejected with=] a "{{NotSupportedError}}" {{DOMException}}.
1. If |options|' |signal| dictionary member is present, and either of |options|' |steal| dictionary member or |options|' |ifAvailable| dictionary member is true, then return [=a promise rejected with=] a "{{NotSupportedError}}" {{DOMException}}.
1. If |options|' |signal| dictionary member is present and its [=AbortSignal/aborted flag=] is set, then return [=a promise rejected with=] an "{{AbortError}}" {{DOMException}.
1. Let |promise| be [=a new promise=].
1. Let |request| be the result of running the steps to [=request a lock=] with |promise|, the current [=/agent=], |environment|'s [=environment/id=], |origin|, |callback|, |name|, |options|' |mode| dictionary member, |options|' |ifAvailable| dictionary member, and |options|' |steal| dictionary member.
1. If |options|' |signal| dictionary member is present, then <a for=AbortSignal lt=add>add the following abort steps</a> to |options|' |signal| dictionary member:
    1. [=enqueue the following steps|Enqueue the steps=] to [=abort the request=] |request| to the [=lock task queue=].
    1. [=Reject=] |promise| with an "{{AbortError}}" {{DOMException}}.
1. Return |promise|.

</div>

<!-- ====================================================================== -->
### The {{LockManager/query()}} method ### {#api-lock-manager-query}
<!-- ====================================================================== -->

<div class=note>
  <dl class=domintro>
    <dt><var>state</var> = await navigator . locks .
        {{LockManager/query()|query}}()</dt>
    <dd>

    The {{LockManager/query()}} method can be used to produce a snapshot of the [=lock manager=] state for an origin, which allows a web application to introspect its usage of locks, for logging or debugging purposes.

    The returned promise resolves to |state|, a plain-old-data structure (i.e. JSON-like data) with this form:

```js
{
  held: [
    { name: "resource1", mode: "exclusive",
      clientId: "8b1e730c-7405-47db-9265-6ee7c73ac153" },
    { name: "resource2", mode: "shared",
      clientId: "8b1e730c-7405-47db-9265-6ee7c73ac153" },
    { name: "resource2", mode: "shared",
      clientId: "fad203a5-1f31-472b-a7f7-a3236a1f6d3b" },
  ],
  pending: [
    { name: "resource1", mode: "exclusive",
      clientId: "fad203a5-1f31-472b-a7f7-a3236a1f6d3b" },
    { name: "resource1", mode: "exclusive",
      clientId: "d341a5d0-1d8d-4224-be10-704d1ef92a15" },
  ]
}
```

    The `clientId` field corresponds to a unique context (frame or worker), and is the same value returned by {{Client}}'s {{Client/id}} attribute.

    </dd>
  </dl>
</div>

<aside class=advisement>
    This data is just a *snapshot* of the [=lock manager=] state at some point in time. By the time the data is returned to script, the actual lock state might have changed.
</aside>


<div class=algorithm>

The <dfn method for=LockManager>query()</dfn> method, when invoked, must run these steps:

1. Let |origin| be [=context object=]'s [=relevant settings object=]'s [=/origin=].
1. If |origin| is an [=opaque origin=], then return [=a promise rejected with=] a "{{SecurityError}}" {{DOMException}}.
1. Let |promise| be [=a new promise=].
1. [=enqueue the following steps|Enqueue the steps=] to [=snapshot the lock state=] for |origin| with |promise| to the [=lock task queue=].
1. Return |promise|.

</div>

<!-- ====================================================================== -->
## {{Lock}} class ## {#api-lock}
<!-- ====================================================================== -->

<xmp class=idl>
[SecureContext, Exposed=(Window,Worker)]
interface Lock {
  readonly attribute DOMString name;
  readonly attribute LockMode mode;
};
</xmp>

A {{Lock}} object has an associated [=lock-concept|lock=].

The {{Lock/name}} attribute getter returns the associated [=lock-concept|lock=]'s [=lock-concept/name=].

The {{Lock/mode}} attribute getter returns the associated [=lock-concept|lock=]'s [=lock-concept/mode=].

<!-- ====================================================================== -->
# Algorithms # {#algorithms}
<!-- ====================================================================== -->

<!-- ====================================================================== -->
## Request a lock ## {#algorithm-request-lock}
<!-- ====================================================================== -->

<div class=algorithm>
To <dfn>request a lock</dfn> with |promise|, |agent|, |clientId|, |origin|, |callback|, |name|, |mode|, |ifAvailable|, |steal|, and optional |signal|:

1. Let |request| be a new [=lock request=] (|agent|, |clientId|, |origin|, |name|, |mode|, |promise|).
1. [=Enqueue the following steps=] to the [=lock task queue=]:
    1. Let |queueMap| be |origin|'s [=lock request queue map=].
    1. Let |queue| be |queueMap|[|name|].
    1. Let |held| be |origin|'s [=held lock set=].
    1. If |steal| is true, then run these steps:
        1. [=list/For each=] |lock| of |held|:
            1. If |lock|'s [=lock-concept/name=] is |name|, then run these steps:
                1. [=list/Remove=] [=lock-concept|lock=] from |held|.
                1. [=Reject=] |lock|'s [=lock-concept/released promise=] with an "{{AbortError}}" {{DOMException}}.
        1. [=list/Prepend=] |request| in |queue|.
    1. Otherwise, run these steps:
        1. If |ifAvailable| is true and |request| is not [=grantable=],
             then [=enqueue the following steps=] on |callback|'s [=relevant settings object=]'s [=responsible event loop=]:
            1. Let |r| be the result of [=invoking=] |callback| with `null` as the only argument.
            1. [=Resolve=] |promise| with |r| and abort these steps.
        1. [=queue/Enqueue=] |request| in |queue|.
    1. [=Process the lock request queue=] |queue|.
1. Return |request|.

</div>

<!-- ====================================================================== -->
## Release a lock ## {#algorithm-release-lock}
<!-- ====================================================================== -->

<div class=algorithm>
To <dfn>release the lock</dfn> |lock|:

1. [=Assert=]: these steps are running on the [=lock task queue=].
1. Let |origin| be |lock|'s [=lock-concept/origin=].
1. Let |queueMap| be |origin|'s [=lock request queue map=].
1. Let |name| be |lock|'s [=resource name=].
1. Let |queue| be |queueMap|[|name|].
1. [=list/Remove=] [=lock-concept|lock=] from the |origin|'s [=held lock set=].
1. [=Process the lock request queue=] |queue|.

</div>

<!-- ====================================================================== -->
## Abort a request ## {#algorithm-abort-request}
<!-- ====================================================================== -->

<div class=algorithm>
To <dfn>abort the request</dfn> |request|:

1. [=Assert=]: these steps are running on the [=lock task queue=].
1. Let |origin| be |request|'s [=lock request/origin=].
1. Let |name| be |lock|'s [=resource name=].
1. Let |queueMap| be |origin|'s [=lock request queue map=].
1. Let |queue| be |queueMap|[|name|].
1. [=list/Remove=] |request| from |queue|.
1. [=Process the lock request queue=] |queue|.

</div>

<!-- ====================================================================== -->
## Process a lock request queue for a given resource name ## {#algorithm-process-request}
<!-- ====================================================================== -->

<div class=algorithm>
To <dfn>process the lock request queue</dfn> |queue|:

1. [=Assert=]: these steps are running on the [=lock task queue=].
1. [=list/For each=] |request| of |queue|:
    1. If |request| is [=grantable=], then run these steps:
        1. [=list/Remove=] |request| from |queue|.
        1. Let |agent| be |request|'s [=lock-concept/agent=]
        1. Let |clientId| be |request|'s [=lock request/clientId=].
        1. Let |name| be |request|'s [=lock request/name=].
        1. Let |mode| be |request|'s [=lock request/mode=].
        1. Let |p| be |request|'s [=lock request/promise=].
        1. Let |waiting| be [=a new promise=].
        1. Let |lock| be a new [=lock-concept|lock=] with [=lock-concept/agent=] |agent|, [=lock-concept/clientId=] |clientId|, [=lock-concept/origin=] |origin|, [=lock-concept/mode=] |mode|, [=lock-concept/name=] |name|, [=lock-concept/released promise=] |p|, and [=lock-concept/waiting promise=] |waiting|.
        1. [=set/Append=] |lock| to |origin|'s [=held lock set=].
        1. [=Enqueue the following steps=] on |callback|'s [=relevant settings object=]'s [=responsible event loop=]:
            1. Let |r| be the result of [=invoking=] |callback| with a new {{Lock}} object associated with |lock| as the only argument.
            1. [=Resolve=] |waiting| with |r|.

</div>

<!-- ====================================================================== -->
## Snapshot the lock state ## {#algorithm-snapshot-state}
<!-- ====================================================================== -->

<div class=algorithm>
To <dfn>snapshot the lock state</dfn> for |origin| with |promise|:

1. [=Assert=]: these steps are running on the [=lock task queue=].
1. Let |pending| be a new [=list=].
1. [=map/For each=] |name| &rarr; |queue| of |origin|'s [=lock request queue map=]:
    1. [=list/For each=] |request| of |queue|:
        1. [=list/Append=] «[ "name" → |request|'s [=lock request/name=], "mode" → |request|'s [=lock request/mode=], "clientId" → |request|'s [=lock request/clientId=] ]» to |pending|.
1. Let |held| be a new [=list=].
1. [=list/For each=] |lock| of |origin|'s [=held lock set=]:
    1. [=list/Append=] «[ "name" → |lock|'s [=lock-concept/name=], "mode" → |lock|'s [=lock-concept/mode=], "clientId" → |lock|'s [=lock-concept/clientId=] ]» to |held|.
1. [=Resolve=] |promise| with «[ "held" → |held|, "pending" → |pending| ]».

</div>

<aside class=note>
<p>
    For any given resource, the snapshot of the pending lock requests
    will return the requests in the order in which they were made;
    however, no guarantees are made with respect to the relative
    ordering of requests across different resources. For example, if
    pending lock requests A1 and A2 are made against resource A in
    that order, and pending lock requests B1 and B2 are made against
    resource B in that order, than both «A1, A2, B1, B2» and «A1, B1,
    A2, B2» would be possible orderings for a snapshot's pending list.
</p>
<p>
    No ordering guarantees exist for the snapshot of the held lock state.
</p>
</aside>

<!-- ====================================================================== -->
# Usage Considerations # {#usage-considerations}
<!-- ====================================================================== -->

*This section is non-normative.*

<!-- ====================================================================== -->
## Deadlocks ## {#deadlocks}
<!-- ====================================================================== -->

[Deadlocks](https://en.wikipedia.org/wiki/Deadlock) are a concept in concurrent computing, and deadlocks scoped to a particular [=lock manager=] can be introduced by this API.

<aside class=example id=example-deadlocks>
An example of how deadlocks can be encountered through the use of this API is as follows.

Script 1:
```js
navigator.locks.request('A', async a => {
  await navigator.locks.request('B', async b => {
    // do stuff with A and B
  });
});
```

Script 2:
```js
navigator.locks.request('B', async b => {
  await navigator.locks.request('A', async a => {
    // do stuff with A and B
  });
});
```

If script 1 and script 2 run close to the same time, there is a chance that script 1 will hold lock A and script 2 will hold lock B and neither can make further progress - a deadlock. This will not affect the user agent as a whole, pause the tab, or affect other script in the origin, but this particular functionality will be blocked.
</aside>

Preventing deadlocks requires care. One approach is to always acquire multiple locks in a strict order.

<aside class=example id=example-request-multiple-locks>

A helper function such as the following could be used to request multiple locks in a consistent order.

```js
async function requestMultiple(resources, callback) {
  const sortedResources = [...resources];
  sortedResources.sort(); // Always request in the same order.

  async function requestNext(locks) {
    return await navigator.locks.request(sortedResources.shift(), async lock => {
      // Now holding this lock, plus all previously requested locks.
      locks.push(lock);

      // Recursively request the next lock in order if needed.
      if (sortedResources.length > 0)
        return await requestNext(locks);

      // Otherwise, run the callback.
      return await callback(locks);

      // All locks will be released when the callback returns (or throws).
    });
  }
  return await requestNext([]);
}
```

In practice, the use of multiple locks is rarely as straightforward &mdash; libraries and other utilities can often unintentionally obfuscate their use.
</aside>


<!-- ====================================================================== -->
# Security and Privacy Considerations # {#security-privacy}
<!-- ====================================================================== -->

<!-- ====================================================================== -->
## Lock Scope ## {#security-scope}
<!-- ====================================================================== -->

The definition of a [=lock manager=]'s scope is important as it defines a privacy boundary. Locks can be used as an ephemeral state retention mechanism and, like storage APIs, can be used as a communication mechanism, and must be no more privileged than storage facilities. User agents that impose finer granularity on one of these services must impose it on others; for example, a user agent that exposes different storage partitions to a top-level page (first-party) and a cross-origin iframe (third-party) in the same origin for privacy reasons must similarly partition locking.

This also provides reasonable expectations for web application authors; if a lock is acquired over a storage resource, all same-origin browsing contexts must observe the same state.

<!-- ====================================================================== -->
## Private Browsing ## {#private-browsing}
<!-- ====================================================================== -->

Every [private mode](https://github.com/w3ctag/private-mode) browsing session is considered a separate user agent for the purposes of this API. That is, locks requested/held outside such a session have no affect on requested/held inside such a session, and vice versa. This prevents a website from determining that a session is "incognito" while also not allowing a communication mechanism between such sessions.

<!-- ====================================================================== -->
## Implementation Risks ## {#implementation-risks}
<!-- ====================================================================== -->

Implementations must ensure that locks do not span origins. Failure to do so would provide a side-channel for communication between script running in two origins, or allow one script in one origin to disrupt the behavior of another (e.g. denying service).

<!-- ====================================================================== -->
## Checklist ## {#security-privacy-checklist}
<!-- ====================================================================== -->

The W3C TAG has developed a [Self-Review Questionnaire: Security and Privacy](https://www.w3.org/TR/security-privacy-questionnaire/) for editors of specifications to informatively answer. Revisiting the questions here:

* The specification does not deal with personally identifiable information, or high-value data.
* No new state for an origin that persists across browsing sessions is introduced.
* No new persistent, cross-origin state is exposed to the web.
* No new data is exposed to an origin that it doesn't currently have access to (e.g. via polling [[IndexedDB-2]].)
* No new script execution/loading mechanisms are enabled.
* This specification does not allow an origin access to any of the following:
    * The user's location.
    * Sensors on a user's device.
    * Aspects of a user's local computing environment.
    * Access to other devices.
    * Any measure of control over a user agent's native UI.
* No temporary identifiers to the web are exposed to the web. All [=resource names=] are provided by the web application itself.
* Behavior in first-party and third-party contexts is distinguished in a user agent if storage is distinguished. See [[#security-scope]].
* Behavior in the context of a user agent's "incognito" mode is described in [[#private-browsing]].
* No data is persisted to a user's local device by this API.
* This API does not allow downgrading default security characteristics.

<!-- ====================================================================== -->
# Acknowledgements # {#acknowledgements}
<!-- ====================================================================== -->

Many thanks to
Alex Russell,
Andreas Butler,
Anne van Kesteren,
Boris Zbarsky,
Darin Fisher,
Domenic Denicola,
Gus Caplan,
Harald Alvestrand,
Jake Archibald,
L. David Baron,
Luciano Pacheco,
Marcos Caceres,
Ralph Chelala,
Raymond Toy,
Ryan Fioravanti,
and
Victor Costan
for helping craft this proposal.

Special thanks to Tab Atkins, Jr. for creating and maintaining
[Bikeshed](https://github.com/tabatkins/bikeshed), the specification
authoring tool used to create this document, and for his general
authoring advice.
