From 00bb0c7d3bebb884cae4991fbf7b824902e64563 Mon Sep 17 00:00:00 2001 From: y00576111 Date: Tue, 30 Nov 2021 17:59:38 +0800 Subject: [PATCH] update readme, add license Signed-off-by: y00576111 Change-Id: I0fbd8e8917adcd4b32564337c0f3b326f5a3102b --- README.en.md | 36 ----- README.md | 331 +++++++++++++++++++++++++++++------------- README.zh.md | 365 +++++++++++++++++++++++++++++++++++++++++++++++ mozilla_docs.txt | 81 +++++++++++ 4 files changed, 681 insertions(+), 132 deletions(-) delete mode 100644 README.en.md create mode 100644 README.zh.md create mode 100644 mozilla_docs.txt diff --git a/README.en.md b/README.en.md deleted file mode 100644 index 0aab6cd..0000000 --- a/README.en.md +++ /dev/null @@ -1,36 +0,0 @@ -# js_worker_module - -#### Description -{**When you're done, you can delete the content in this README and update the file with details for others getting started with your repository**} - -#### Software Architecture -Software architecture description - -#### Installation - -1. xxxx -2. xxxx -3. xxxx - -#### Instructions - -1. xxxx -2. xxxx -3. xxxx - -#### Contribution - -1. Fork the repository -2. Create Feat_xxx branch -3. Commit your code -4. Create Pull Request - - -#### Gitee Feature - -1. You can use Readme\_XXX.md to support different languages, such as Readme\_en.md, Readme\_zh.md -2. Gitee blog [blog.gitee.com](https://blog.gitee.com) -3. Explore open source project [https://gitee.com/explore](https://gitee.com/explore) -4. The most valuable open source project [GVP](https://gitee.com/gvp) -5. The manual of Gitee [https://gitee.com/help](https://gitee.com/help) -6. The most popular members [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/) diff --git a/README.md b/README.md index d501406..ef33b38 100644 --- a/README.md +++ b/README.md @@ -1,235 +1,374 @@ # js_worker_module -#### 一、Worker介绍 +### Introduction -worker能够让js拥有多线程的能力，通过postMessage完成worker线程与宿主线程通信。 +Worker enables JS to have the ability of multithreading, and completes the communication between worker thread and host thread through PostMessage. -一. Worker介绍 +### Interface description +For interface implementation, see: js_worker_module/jsapi/worker -接口介绍 +#### Worker object description -1.constructor(scriptURL:string, options? WorkerOptions); -构造函数 +The object object used by the host thread to communicate with the worker thread. -使用方法: +##### Interface + +1. + +- name + +|constructor(scriptURL:string, options? WorkerOptions) | worker constructor to Creates a worker instance | +|---|---| + +- example + +``` import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); +``` -2. postMessage(message:Object, options?:PostMessageOptions): void; -描述: -向worker线程发送消息，数据的传输采用结构化算法 +2. -使用方法: +- name -示例一 +| postMessage(message:Object, options?:PostMessageOptions) | Sends a message to the worker thread | +|---|---| +| postMessage(message:Object, transfer:ArrayBuffer[]) | Sends a message to the worker thread | + +- example + +``` +// example 1 import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); worker.postMessage("hello world"); - -示例二 + +// example 2 import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); -var buffer = new ArrayBuffer(8) +var buffer = new ArrayBuffer(8); worker.postMessage(buffer, [buffer]); +``` -3. on(type:string, listener:EventListener):void; -描述: -向worker添加一个事件监听 +3. -使用方法: +- name + +| on(type:string, listener:EventListener) | Adds an event listener to the worker | +|---|---| + +- example + +``` import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); worker.on("alert", (e)=>{ - console.log("worker on..."); + console.log("worker on..."); }) +``` -4. once(type:string, listener:EventListener):void; -描述: -向worker添加一个事件监听, 事件监听只执行一次，一旦出发便会自动删除 +4. -使用方法 +- name + +| once(type:string, listener:EventListener) | Adds an event listener to the worker and + removes the event listener automically after it is invoked once | +|---|---| + +- example + +``` import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); worker.once("alert", (e)=>{ console.log("worker on..."); }) +``` -5. off(type:string, listener?:EventListener):void; -描述: -删除worker的事件监听 +5. -使用方法 +- name + +| off(type:string, listener?:EventListener) | Removes an event listener to the worker | +|---|---| + +- example + +``` import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); worker.off("alert"); +``` -6. terminate():void; -描述: -关闭worker线程，终止worker发送消息 +6. -使用方法 +- name + +| terminate() | Terminates the worker thread to stop the worker from receiving messages | +|---|---| + +- example + +``` import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); worker.terminate(); +``` -7. removeEventListener(type:string, listener?:EventListener):void; -描述: -删除worker的事件监听 +7. -使用方法 +- name + +| removeEventListener(type:string, listener?:EventListener) | Removes an event defined for the worker | +|---|---| + +- example + +``` import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); worker.removeEventListener("alert"); +``` -8. dispatchEvent(event: Event):boolean; -描述: -分发worker的事件监听 +8. -使用方法 +- name + +| dispatchEvent(event: Event) | Dispatches the event defined for the worker | +|---|---| + +- example + +``` import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); worker.dispatchEvent({type:"alert"}); +``` -9. removeAllEventListener(): void; -描述: -删除worker的所有事件监听 +9. -使用方法 +- name + +| removeAllListener() | Removes all event listeners for the worker | +|---|---| + +- example + +``` import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); -worker.removeAllEventListener(); +worker.removeAllListener(); +``` -10. onexit?:(code:number)=>void; -描述: -worker退出时出发js线程的回调方法 +##### Attribute -使用方法 +1. + +- name + +| onexit?:(code:number)=>void | The onexit attribute of the worker specifies the event handler to be called + when the worker exits. The handler is executed in the host thread | +|---|---| + +- example + +``` import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); worker.onexit = function(e) { console.log("onexit..."); } +``` -11. onerror?:(ev:ErrorEvent)=>void; -描述: -worker内部执行js发生异常触发的宿主线程回调 +2. -使用方法: +- name + +| onerror?:(ev:ErrorEvent)=>void | The onerror attribute of the worker specifies the event handler to be called + when an exception occurs during worker execution. The event handler is executed in the host thread | +|---|---| + +- example + +``` import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); worker.onerror = function(e) { console.log("onerror..."); } +``` -12. onmessage?:(ev:MessageEvent)=>void; -描述: -当宿主线程接受到来自其创建的worker消息时，会在worker对象上触发message事件。例如，当worker通过parentPort.postMessage()发送了一条消息 +3. -使用方法: +- name + +| onmessage?:(ev:MessageEvent)=>void | The onmessage attribute of the worker specifies the event handler to be called + then the host thread receives a message created by itself and sent by the worker through the parentPort.postMessage. + The event handler is executed in the host thread | +|---|---| + +- example + +``` import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); worker.onmessage = function(e) { console.log("onmessage..."); } +``` -13. onmessageerror?:(event:MessageEvent)=>void; -描述: -worker对象接收到一条无法序列化的消息时，messageerror事件将在该对象上被触发 +4. -使用方法: +- name + +| onmessageerror?:(event:MessageEvent)=>void | The onmessage attribute of the worker specifies the event handler + when the worker receives a message that cannot be serialized. The event handler is executed in the host thread | +|---|---| + +- example + +``` import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); worker.onmessageerror = function(e) { console.log("onmessageerror..."); } +``` -二. parentPort介绍 -描述: -worker线程用于与宿主线程通信的Object对象，通过parentPort接口发送消息给主线程、close接口关闭worker线程 +#### parentPort object description -接口介绍 +Object of the worker thread used to communicate with the host thread -1. parent.postMessage(message:Object, options?:PostMessageOptions): void; -描述: -worker向宿主线程发送消息 +##### Interface -使用方法: -main.js +1. + +- name + +| postMessage(message:Object, options?:PostMessageOptions) | Send a message to host thread | +|---|---| +| postMessage(message:Object, transfer:ArrayBuffer[]) | Send a message to host thread | + +- example + +``` +// main.js import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); worker.postMessage("hello world"); -worker.js +// worker.js import worker from "@ohos.worker" const parentPort = worker.parentPort; parentPort.onmessage = function(e) { parentPort.postMessage("hello world from worker.js"); } +``` -2. parent.close():void -描述: -关闭worker线程，终止worker接收消息 +2. -使用方法: -main.js +- name + +| close() | Close the worker thread to stop the worker from receiving messages | +|---|---| + +- example + +``` +// main.js import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); worker.postMessage("hello world"); -worker.js +// worker.js import worker from "@ohos.worker" const parentPort = worker.parentPort; parentPort.onmessage = function(e) { parentPort.close(); } +``` -3. parent.onmessage?:(event:MessageEvent)=>void -描述: -parent接口的onmessage属性表示在消息事件发生时要调用的事件处理程序，即当使用worker.postMessage方法将消息发送至worker时 +##### Attribute -使用方法： -main.js +1. + +- name + +| onmessage?:(event:MessageEvent)=>void | The onmessage attribute of parentPort specifies the event handler to be called + then the worker thread receives a message sent by the host thread through worker postMessage. + The event handler is executed in the worker thread | +|---|---| + +- example + +``` +// main.js import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); worker.postMessage("hello world"); -worker.js +// worker.js import worker from "@ohos.worker" const parentPort = worker.parentPort; parentPort.onmessage = function(e) { console.log("receive main.js message"); } +``` -4. parentPort.onerror?:(ev: ErrorEvent)=>void; -描述: -worker线程内部执行js发生异常触发的worker回调 +2. -使用方法： -main.js +- name + +| onerror?:(ev: ErrorEvent)=>void | The onerror attribute of parentPort specifies the event handler to be called + when an exception occurs during worker execution. The event handler is executed in the worker thread | +|---|---| + +- example + +``` +// main.js import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); worker.postMessage("hello world"); -worker.js +// worker.js import worker from "@ohos.worker" const parentPort = worker.parentPort; parentPort.onerror = function(e) { console.log("onerror..."); } -5. parentPort.onmessageerror?:(event: MessageEvent)=>void; -描述: -当worker接收到一条无法被反序列化的消息时，messageerror将在该事件上触发 +``` -使用方法： -main.js +3. + +- name + +| onmessageerror?:(event: MessageEvent)=>void | The onmessage attribute of parentPort specifies the event handler to be called + then the worker receives a message that cannot be deserialized. The event handler is executed in the worker thread. | +|---|---| + +- example + +``` +// main.js import worker from "@ohos.worker" const worker = new worker.Worker("workers/worker.js"); worker.postMessage("hello world"); -worker.js +// worker.js import worker from "@ohos.worker" const parentPort = worker.parentPort; parentPort.onmessageerror = function(e) { console.log("onmessageerror..."); -} \ No newline at end of file +} +``` + +### Repositories Involved + +- ace_ace_engine +- ace_napi + +### License + +Worker is available under [Mozilla license](https://www.mozilla.org/en-US/MPL/), and the documentation is detailed in [documentation](https://gitee.com/openharmony/js_worker_module/blob/master/mozilla_docs.txt). See [LICENSE](https://gitee.com/openharmony/js_worker_module/blob/master/LICENSE) for the full license text. \ No newline at end of file diff --git a/README.zh.md b/README.zh.md new file mode 100644 index 0000000..30cc5ac --- /dev/null +++ b/README.zh.md @@ -0,0 +1,365 @@ +# js_worker_module + +### 简介 + +worker能够让js拥有多线程的能力，通过postMessage完成worker线程与宿主线程通信。 + +### 接口说明 +接口实现详见：js_worker_module/jsapi/worker + +#### Worker对象描述 + +宿主线程用于与worker线程通信的Object对象。 + +##### 接口 + +1. + +- 接口名 + +|constructor(scriptURL:string, options? WorkerOptions) | 构造函数 | +|---|---| + +- 使用示例 + +``` +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +``` + +2. + +- 接口名 + +| postMessage(message:Object, options?:PostMessageOptions) | 向worker线程发送消息 | +|---|---| +| postMessage(message:Object, transfer:ArrayBuffer[]) | 向worker线程发送消息 | + +- 使用示例 + +``` +// 示例一 +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.postMessage("hello world"); + +// 示例二 +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +var buffer = new ArrayBuffer(8); +worker.postMessage(buffer, [buffer]); +``` + +3. + +- 接口名 + +| on(type:string, listener:EventListener) | 向worker添加一个事件监听 | +|---|---| + +- 使用示例 + +``` +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.on("alert", (e)=>{ + console.log("worker on..."); +}) +``` + +4. + +- 接口名 + +| once(type:string, listener:EventListener) | 向worker添加一个事件监听, 事件监听只执行一次便自动删除 | +|---|---| + +- 使用示例 + +``` +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.once("alert", (e)=>{ + console.log("worker on..."); +}) +``` + +5. + +- 接口名 + +| off(type:string, listener?:EventListener) | 删除worker的事件监听 | +|---|---| + +- 使用示例 + +``` +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.off("alert"); +``` + +6. + +- 接口名 + +| terminate() | 关闭worker线程，终止worker发送消息 | +|---|---| + +- 使用示例 + +``` +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.terminate(); +``` + +7. + +- 接口名 + +| removeEventListener(type:string, listener?:EventListener) | 删除worker的事件监听 | +|---|---| + +- 使用示例 + +``` +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.removeEventListener("alert"); +``` + +8. + +- 接口名 + +| dispatchEvent(event: Event) | 分发定义在worker的事件 | +|---|---| + +- 使用示例 + +``` +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.dispatchEvent({type:"alert"}); +``` + +9. + +- 接口名 + +| removeAllListener() | 删除worker的所有事件监听 | +|---|---| + +- 使用示例 + +``` +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.removeAllListener(); +``` + +##### 属性 + +1. + +- 属性名 + +| onexit?:(code:number)=>void | worker退出时被调用的事件处理程序，处理程序在宿主线程中执行 | +|---|---| + +- 使用示例 + +``` +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.onexit = function(e) { + console.log("onexit..."); +} +``` + +2. + +- 属性名 + +| onerror?:(ev:ErrorEvent)=>void | worker在执行过程中发生异常被调用的事件处理程序，处理程序在宿主线程中执行 | +|---|---| + +- 使用示例 + +``` +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.onerror = function(e) { + console.log("onerror..."); +} +``` + +3. + +- 属性名 + +| onmessage?:(ev:MessageEvent)=>void | 宿主线程收到来自其创建的worker通过parentPort.postMessage接口发送的消息时被调用的事件处理程序， 处理程序在宿主线程中执行 | +|---|---| + +- 使用示例 + +``` +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.onmessage = function(e) { + console.log("onmessage..."); +} +``` + +4. + +- 属性名 + +| onmessageerror?:(event:MessageEvent)=>void | worker对象接收到一条无法序列化的消息时被调用的事件处理程序， 处理程序在宿主线程中执行 | +|---|---| + +- 使用示例 + +``` +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.onmessageerror = function(e) { + console.log("onmessageerror..."); +} +``` + +#### parentPort对象描述 + +worker线程用于与宿主线程通信的Object对象。 + +##### 接口 + +1. + +- 接口名 + +| postMessage(message:Object, options?:PostMessageOptions) | 向宿主线程发送消息 | +|---|---| +| postMessage(message:Object, transfer:ArrayBuffer[]) | 向宿主线程发送消息 | + +- 使用示例 + +``` +// main.js +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.postMessage("hello world"); + +// worker.js +import worker from "@ohos.worker" +const parentPort = worker.parentPort; +parentPort.onmessage = function(e) { + parentPort.postMessage("hello world from worker.js"); +} +``` + +2. + +- 接口名 + +| close() | 关闭worker线程，终止worker接收消息 | +|---|---| + +- 使用示例 + +``` +// main.js +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.postMessage("hello world"); + +// worker.js +import worker from "@ohos.worker" +const parentPort = worker.parentPort; +parentPort.onmessage = function(e) { + parentPort.close(); +} +``` + +##### 属性 + +1. + +- 属性名 + +| onmessage?:(event:MessageEvent)=>void | 宿主线程收到来自其创建的worker通过worker.postMessage接口发送的消息时被调用的事件处理程序， + 处理程序在worker线程中执行 | +|---|---| + +- 使用示例 + +``` +// main.js +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.postMessage("hello world"); + +// worker.js +import worker from "@ohos.worker" +const parentPort = worker.parentPort; +parentPort.onmessage = function(e) { + console.log("receive main.js message"); +} +``` + +2. + +- 属性名 + +| onerror?:(ev: ErrorEvent)=>void | worker在执行过程中发生异常被调用的事件处理程序，处理程序在worker线程中执行 | +|---|---| + +- 使用示例 + +``` +// main.js +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.postMessage("hello world"); + +// worker.js +import worker from "@ohos.worker" +const parentPort = worker.parentPort; +parentPort.onerror = function(e) { + console.log("onerror..."); +} + +``` + +3. + +- 属性名 + +| onmessageerror?:(event: MessageEvent)=>void | worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序， 处理程序在worker线程中执行 | +|---|---| + +- 使用示例 + +``` +// main.js +import worker from "@ohos.worker" +const worker = new worker.Worker("workers/worker.js"); +worker.postMessage("hello world"); + +// worker.js +import worker from "@ohos.worker" +const parentPort = worker.parentPort; +parentPort.onmessageerror = function(e) { + console.log("onmessageerror..."); +} +``` + +### 涉及仓 + +- ace_ace_engine +- ace_napi + +### 许可证 + +Worker在[Mozilla许可证](https://www.mozilla.org/en-US/MPL/)下可用，说明文档详见[说明文档](https://gitee.com/openharmony/js_worker_module/blob/master/mozilla_docs.txt)。有关完整的许可证文本，有关完整的许可证文本，请参见[许可证](https://gitee.com/openharmony/js_worker_module/blob/master/LICENSE) \ No newline at end of file diff --git a/mozilla_docs.txt b/mozilla_docs.txt new file mode 100644 index 0000000..3e88cf7 --- /dev/null +++ b/mozilla_docs.txt @@ -0,0 +1,81 @@ + +The definitions of some interfaces implemented in jsapi/workers/worker.cpp are released under Mozilla license. + +The definitions and functions of these interfaces are consistent with the standard interfaces under mozila license, +but the implementation of specific functions is independent and self-developed. + +All interfaces are described in d.ts, the following is the interface written in d.ts under to Mozilla license + +export interface WorkerOptions { + type?: "classic" | "module"; + name?: string; + shared?: boolean; +} + +export interface Event { + readonly type: string; + readonly timeStamp: number; +} + +interface ErrorEvent extends Event { + readonly message: string; + readonly filename: string; + readonly lineno: number; + readonly colno: number; + readonly error: Object; +} + +declare interface MessageEvent extends Event { + readonly data: T; +} + +export interface PostMessageOptions { + transfer?: Object[]; +} + +export interface EventListener { + (evt: Event): void | Promise; +} + +type MessageType = "message" | "messageerror"; + +declare interface EventTarget { + addEventListener( + type: string, + listener: EventListener + ): void; + dispatchEvent(event: Event): boolean; + removeEventListener( + type: string, + callback?: EventListener + ): void; + removeAllListener(): void; +} + +declare interface WorkerGlobalScope extends EventTarget { + readonly name: string; + onerror?: (ev: ErrorEvent) => void; + readonly self: WorkerGlobalScope & typeof globalThis; +} + +declare interface DedicatedWorkerGlobalScope extends WorkerGlobalScope { + onmessage?: (this: DedicatedWorkerGlobalScope, ev: MessageEvent) => void; + onmessageerror?: (this: DedicatedWorkerGlobalScope, ev: MessageEvent) => void; + close(): void; + postMessage(messageObject: Object, transfer: Transferable[]): void; + postMessage(messageObject: Object, options?: PostMessageOptions): void; +} + +declare namespace worker { + class Worker extends EventTarget { + constructor(scriptURL: string, options?: WorkerOptions); + onexit?: (code: number) => void; + onerror?: (err: ErrorEvent) => void; + onmessage?: (event: MessageEvent) => void; + onmessageerror?: (event: MessageEvent) => void; + postMessage(message: Object, transfer: ArrayBuffer[]): void; + postMessage(message: Object, options?: PostMessageOptions): void; + terminate(): void; + } + const parentPort: DedicatedWorkerGlobalScope; +} \ No newline at end of file