Workers API

Support for Workers

For iOS solution please check - https://github.com/NativeScript/ios-runtime/issues/620

Description

General guidelines for the Workers implementation effort and specification in the context of NativeScript.
We have an existing issue here, but the purpose here is to show the road map that the team intends to follow in developing the Workers functionality. The general scenarios we want to support are listed at the bottom.

Limitations

In NativeScript we don’t need to implement all details of the web workers specification, because some of these details are only related to the browser, and won’t have any meaning in the context of a NativeScript application. The features and syntax that will follow has the purpose of describing the adoption of the web workers specification in NativeScript. In this document we will describe and list what we intend to support.

Guidelines from the specification to follow

context

Notice that onmessage and postMessage() need to be hung off the Worker object when used in the main script thread, but not when used in the worker. This is because, inside the worker, the worker is effectively the global scope.

messaging specifics

Data passed between the main thread and workers is copied, not shared. Objects are serialized as they're handed to the worker, and subsequently, deserialized on the other end. The page and worker do not share the same instance, so the end result is that a duplicate is created on each end. Most browsers implement this feature as structured cloning.
The structured cloning algorithm can accept JSON and a few things that JSON can't — like circular references.

messaging transfer ownership

Passing data by transferring ownership (transferable objects): in nativescript we can try to pass native objects by transferring ownership on them.

onerror spec

The error event has the following three fields that are of interest:
message: A human-readable error message.
filename: The name of the script file in which the error occurred.
lineno: The line number of the script file on which the error occurred.

importScripts

ImportScripts in a nativescript context mean require. If we want to support this syntax we need an alias for require.

Syntax

The following example will be the general syntax to use when working with Workers. Syntax is based on web worker specification.

<app_name>/app/main.js

// create new worker
var myWorker = new Worker("worker.js");

// on worker error handler
myWorker.onerror = function (e) {
 //do on worker error
}

// receive messages from worker
myWorker.onmessage = function (e) {
  result.textContent = e.data;
}
....
// send messages to worker
myWorker.postMessage("message will be sent to worker");

//The worker thread is killed immediately without an opportunity to complete its operations or clean up after itself.
myWorker.terminate();

myWorker.onclose = function () {
//on close (clean up)
}

---

<app_name>/app/worker.js

onmessage = function(e) {
  postMessage(e.data); // worker -> main
}

//worker closes it self
close();

Supported APIs:

Worker Object:

• Worker.onerror
• Worker.onmessage
• Worker.postMessage()
• Worker.terminate()

Worker Global Object:

• WorkerGlobalObject.self
• WorkerGlobalObject.onmessage
• WorkerGlobalObject.onerror
• WorkerGlobalObject.onclose
• WorkerGlobalObject.close()
• WorkerGlobalObject.postMessage()
• WorkerGlobalObject.importScripts()

Implementation steps:

• Run pure javascript file on new thread
  • Initialize the android runtime on new thread
  • Create a run loop on the newly created thread and schedule the runtime on it
• Enable require of pure javascript files from new thread
• Implement error handling per thread
  • Try/catch should work like it does in the main thread
  • When error is not caught, call onerror handler of the worker object on the main thread
  • Throw error when calling UI APIs on worker thread (if possible)
• Call native non-ui APIs from javascript file running on thread
  • android runtime tests pass on worker thread
• Implement messaging API to communicate between threads (main -> worker, worker->main)
  • Simple object
  • Simple object and an ArrayBuffer as a second parameter
  • Native objects (change of ownership instead of copy)
• Enable tns-module support (will extend later)
• Debugging
  • Resarch what should be done on the backend side in order to support worker debugging
  • Debugging support in NativeScriptAppInspector client
  • Debugging support in VSCode
• Add tests
  • Callback tests
  • Parameters/Properties/Ctor tests
  • Lifecycle tests
  • GC tests
• Update documentation

この issue では例として <app_name>/app/main.js と <app_name>/app/worker.js のエントリーポイントしか示されていません。まず、既存の Worker 実装と、その callback、ライフサイクル、GC、メッセージングのテストを見つけてください。これらの領域を未チェックのチェックリスト項目と比較し、残っている特定の項目について合意済みのスコープが定まり、テストカバレッジが通るまでは、作業が完了したとはみなさないでください。