worker: implement web locks api

devsnek · devsnek · commit 44532ff44651 · 2018-09-06T20:50:30.000-05:00
diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md
@@ -92,6 +92,106 @@ added: v10.5.0
 An arbitrary JavaScript value that contains a clone of the data passed
 to this thread’s `Worker` constructor.
 
+## worker.locks
+<!-- YAML
+added: REPLACEME
+-->
+
+* {LockManager}
+
+An instance of a [`LockManager`][].
+
+## Class: Lock
+<!-- YAML
+added: REPLACEME
+-->
+
+The Lock interface provides the name and mode of a previously requested lock,
+which is received in the callback to [`LockManager.request()`][].
+
+### lock.name
+<!-- YAML
+added: REPLACEME
+-->
+
+* {string}
+
+The name of this lock.
+
+### lock.mode
+<!-- YAML
+added: REPLACEME
+-->
+
+* {string}
+
+The mode of this lock. Either `shared` or `exclusive`.
+
+## Class: LockManager
+<!-- YAML
+added: REPLACEME
+-->
+
+The `LockManager` interface provides methods for requesting a new [`Lock`][]
+object and querying for an existing `Lock` object. To get an instance of
+`LockManager`, call `worker_threads.locks`.
+
+With the exception of `AbortController` support, this implementation matches
+the [browser `LockManager`][] API.
+
+### locks.request(name[, options], callback)
+<!-- YAML
+added: REPLACEME
+-->
+
+* `name` {string}
+* `options` {Object}
+  * `mode` {string} Either `'exclusive'` or `'shared'`. **Default:**
+    `'exclusive'`.
+  * `ifAvailable` {boolean} If `true`, the lock request will only be
+    granted if it is not already held. If it cannot be granted, the
+    callback will be invoked with `null` instead of a `Lock` instance.
+    **Default:** `false`.
+  * `steal` {boolean} If `true`, then any held locks with the same name will be
+    released, and the request will be granted, preempting any queued requests
+    for it. **Default:** `false`.
+* `callback` {Function} The function to be invoked while the lock is acquired.
+  The lock will be released when the function ends, or if the function returns
+  a promise, when that promise settles.
+* Returns: {Promise}
+
+Requests a [`Lock`][] object with parameters specifying its name and
+characteristics.
+
+```js
+worker_threads.locks.request('my_resource', async (lock) => {
+  // The lock was granted.
+}).then(() => {
+  // The lock is released here.
+});
+```
+
+### locks.query()
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {Promise}
+
+Returns a Promise that resolves with a [`LockManagerSnapshot`][] which contains
+information about held and pending locks.
+
+```js
+worker_threads.locks.query().then((state) => {
+  state.held.forEach((lock) => {
+    console.log(`held lock: name ${lock.name}, mode ${lock.mode}`);
+  });
+  state.pending.forEach((request) => {
+    console.log(`requested lock: name ${request.name}, mode ${request.mode}`);
+  });
+});
+```
+
 ## Class: MessageChannel
 <!-- YAML
 added: v10.5.0
@@ -483,10 +583,14 @@ active handle in the event system. If the worker is already `unref()`ed calling
 [`require('worker_threads').threadId`]: #worker_threads_worker_threadid
 [`cluster` module]: cluster.html
 [`inspector`]: inspector.html
+[`Lock`]: #worker_threads_class_lock
+[`LockManager`]: #worker_threads_class_lockmanager
+[`LockManagerSnapshot`]: https://developer.mozilla.org/en-US/docs/Web/API/LockManagerSnapshot
 [v8.serdes]: v8.html#v8_serialization_api
 [`SharedArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
 [Signals events]: process.html#process_signal_events
 [`Uint8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
+[browser `LockManager`]: https://developer.mozilla.org/en-US/docs/Web/API/LockManager
 [browser `MessagePort`]: https://developer.mozilla.org/en-US/docs/Web/API/MessagePort
 [child processes]: child_process.html
 [HTML structured clone algorithm]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
diff --git a/lib/internal/worker.js b/lib/internal/worker.js
@@ -15,8 +15,10 @@ const {
 const { internalBinding } = require('internal/bootstrap/loaders');
 const { MessagePort, MessageChannel } = internalBinding('messaging');
 const { handle_onclose } = internalBinding('symbols');
+const locks = internalBinding('locks');
 const { clearAsyncIdStack } = require('internal/async_hooks');
 const { serializeError, deserializeError } = require('internal/error-serdes');
+const DOMException = require('internal/domexception');
 
 util.inherits(MessagePort, EventEmitter);
 
@@ -44,6 +46,7 @@ const kStdioWantsMoreDataCallback = Symbol('kStdioWantsMoreDataCallback');
 const kStartedReading = Symbol('kStartedReading');
 const kWaitingStreams = Symbol('kWaitingStreams');
 const kIncrementsPortRef = Symbol('kIncrementsPortRef');
+const kMode = Symbol('mode');
 
 const debug = util.debuglog('worker');
 
@@ -505,12 +508,159 @@ function pipeWithoutWarning(source, dest) {
   dest._maxListeners = destMaxListeners;
 }
 
+// https://wicg.github.io/web-locks/#api-lock
+class Lock {
+  constructor() {
+    // eslint-disable-next-line no-restricted-syntax
+    throw new TypeError('Illegal constructor');
+  }
+
+  get name() {
+    return this[kName];
+  }
+
+  get mode() {
+    return this[kMode];
+  }
+}
+
+Object.defineProperties(Lock.prototype, {
+  name: { enumerable: true },
+  mode: { enumerable: true },
+  [Symbol.toStringTag]: {
+    value: 'Lock',
+    writable: false,
+    enumerable: false,
+    configurable: true,
+  },
+});
+
+// https://wicg.github.io/web-locks/#api-lock-manager
+class LockManager {
+  constructor() {
+    // eslint-disable-next-line no-restricted-syntax
+    throw new TypeError('Illegal constructor');
+  }
+
+  // https://wicg.github.io/web-locks/#api-lock-manager-request
+  request(name, options, callback) {
+    if (callback === undefined) {
+      callback = options;
+      options = undefined;
+    }
+
+    // Let promise be a new promise.
+    let reject;
+    let resolve;
+    const promise = new Promise((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+
+    // If options was not passed, then let options be a new LockOptions
+    // dictionary with default members.
+    if (options === undefined) {
+      options = {
+        mode: 'exclusive',
+        ifAvailable: false,
+        steal: false,
+      };
+    }
+
+    if (name.startsWith('-')) {
+      // if name starts with U+002D HYPHEN-MINUS (-), then reject promise with a
+      // "NotSupportedError" DOMException.
+      reject(new DOMException('NotSupportedError'));
+    } else if (options.ifAvailable === true && options.steal === true) {
+      // Otherwise, if both options' steal dictionary member and option's
+      // ifAvailable dictionary member are true, then reject promise with a
+      // "NotSupportedError" DOMException.
+      reject(new DOMException('NotSupportedError'));
+    } else if (options.steal === true && options.mode !== 'exclusive') {
+      // Otherwise, if options' steal dictionary member is true and option's
+      // mode dictionary member is not "exclusive", then reject promise with a
+      // "NotSupportedError" DOMException.
+      reject(new DOMException('NotSupportedError'));
+    } else {
+      // Otherwise, run these steps:
+
+      // Let request be the result of running the steps to request a lock with
+      // promise, the current agent, environment's id, origin, callback, name,
+      // options' mode dictionary member, options' ifAvailable dictionary
+      // member, and option's steal dictionary member.
+      process.nextTick(() => {
+        locks.request(
+          promise,
+          (name, mode, waitingPromise, release) => {
+            const lock = Object.create(Lock.prototype, {
+              [kName]: {
+                value: name,
+                writable: false,
+                enumerable: false,
+                configurable: false,
+              },
+              [kMode]: {
+                value: mode === 0 ? 'shared' : 'exclusive',
+                writable: false,
+                enumerable: false,
+                configurable: false,
+              },
+            });
+
+            // When lock lock's waiting promise settles (fulfills or rejects),
+            // enqueue the following steps on the lock task queue:
+            waitingPromise
+              .finally(() => undefined)
+              .then(() => {
+                // Release the lock lock.
+                release();
+
+                // Resolve lock's released promise with lock's waiting promise.
+                resolve(waitingPromise);
+              });
+
+            return callback(lock);
+          },
+          name,
+          options.mode === 'shared' ? 0 : 1,
+          options.ifAvailable,
+          options.steal);
+      });
+    }
+
+    // Return promise.
+    return promise;
+  }
+
+  // https://wicg.github.io/web-locks/#api-lock-manager-query
+  query() {
+    return new Promise((resolve) => {
+      process.nextTick(() => {
+        const snapshot = locks.snapshot();
+        resolve(snapshot);
+      });
+    });
+  }
+}
+
+Object.defineProperties(LockManager.prototype, {
+  request: { enumerable: true },
+  query: { enumerable: true },
+  [Symbol.toStringTag]: {
+    value: 'LockManager',
+    writable: false,
+    enumerable: false,
+    configurable: true,
+  },
+});
+
 module.exports = {
   MessagePort,
   MessageChannel,
   threadId,
   Worker,
   setupChild,
   isMainThread,
-  workerStdio
+  workerStdio,
+  LockManager,
 };
diff --git a/lib/worker_threads.js b/lib/worker_threads.js
@@ -5,7 +5,8 @@ const {
   MessagePort,
   MessageChannel,
   threadId,
-  Worker
+  Worker,
+  LockManager,
 } = require('internal/worker');
 
 module.exports = {
@@ -14,5 +15,6 @@ module.exports = {
   MessageChannel,
   threadId,
   Worker,
-  parentPort: null
+  parentPort: null,
+  locks: Object.create(LockManager.prototype),
 };
diff --git a/node.gyp b/node.gyp
@@ -350,6 +350,7 @@
         'src/node_file.cc',
         'src/node_http2.cc',
         'src/node_http_parser.cc',
+        'src/node_locks.cc',
         'src/node_messaging.cc',
         'src/node_options.cc',
         'src/node_os.cc',
@@ -413,6 +414,7 @@
         'src/node_http2_state.h',
         'src/node_internals.h',
         'src/node_javascript.h',
+        'src/node_locks.h',
         'src/node_messaging.h',
         'src/node_mutex.h',
         'src/node_options.h',
diff --git a/src/env.h b/src/env.h
@@ -153,6 +153,7 @@ struct PackageConfig {
   V(duration_string, "duration")                                              \
   V(emit_warning_string, "emitWarning")                                       \
   V(exchange_string, "exchange")                                              \
+  V(exclusive_string, "exclusive")                                            \
   V(encoding_string, "encoding")                                              \
   V(entries_string, "entries")                                                \
   V(entry_type_string, "entryType")                                           \
@@ -178,6 +179,7 @@ struct PackageConfig {
   V(get_shared_array_buffer_id_string, "_getSharedArrayBufferId")             \
   V(gid_string, "gid")                                                        \
   V(handle_string, "handle")                                                  \
+  V(held_string, "held")                                                      \
   V(help_text_string, "helpText")                                             \
   V(homedir_string, "homedir")                                                \
   V(host_string, "host")                                                      \
@@ -201,6 +203,7 @@ struct PackageConfig {
   V(message_port_string, "messagePort")                                       \
   V(message_port_constructor_string, "MessagePort")                           \
   V(minttl_string, "minttl")                                                  \
+  V(mode_string, "mode")                                                      \
   V(modulus_string, "modulus")                                                \
   V(name_string, "name")                                                      \
   V(netmask_string, "netmask")                                                \
@@ -242,6 +245,7 @@ struct PackageConfig {
   V(parse_error_string, "Parse Error")                                        \
   V(password_string, "password")                                              \
   V(path_string, "path")                                                      \
+  V(pending_string, "pending")                                                \
   V(pending_handle_string, "pendingHandle")                                   \
   V(pid_string, "pid")                                                        \
   V(pipe_string, "pipe")                                                      \
@@ -270,6 +274,7 @@ struct PackageConfig {
   V(service_string, "service")                                                \
   V(servername_string, "servername")                                          \
   V(session_id_string, "sessionId")                                           \
+  V(shared_string, "shared")                                                  \
   V(shell_string, "shell")                                                    \
   V(signal_string, "signal")                                                  \
   V(sink_string, "sink")                                                      \
diff --git a/src/node_internals.h b/src/node_internals.h
@@ -117,6 +117,7 @@ struct sockaddr;
     V(http_parser)                                                            \
     V(inspector)                                                              \
     V(js_stream)                                                              \
+    V(locks)                                                                  \
     V(messaging)                                                              \
     V(module_wrap)                                                            \
     V(options)                                                                \
diff --git a/src/node_locks.cc b/src/node_locks.cc
diff --git a/src/node_locks.h b/src/node_locks.h
diff --git a/tools/doc/type-parser.js b/tools/doc/type-parser.js
