From 461c13d84ea2e54950f2b3a29c878f2a94af9001 Mon Sep 17 00:00:00 2001 From: yqhan Date: Wed, 28 Jun 2023 09:40:25 +0800 Subject: [PATCH] Modify the doc of worker module. Signed-off-by: yqhan --- .../reference/apis/js-apis-worker.md | 79 ++++++++++--------- 1 file changed, 40 insertions(+), 39 deletions(-) diff --git a/zh-cn/application-dev/reference/apis/js-apis-worker.md b/zh-cn/application-dev/reference/apis/js-apis-worker.md index 4738fe5e25..64c8b9a39f 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-worker.md +++ b/zh-cn/application-dev/reference/apis/js-apis-worker.md @@ -160,9 +160,9 @@ Stage模型: ### postMessage9+ -postMessage(message: Object, transfer: ArrayBuffer[]): void; +postMessage(message: Object, transfer: ArrayBuffer[]): void -向Worker线程发送数据，数据类型必须是序列化所支持的类型。序列化支持类型见其他说明。 +宿主线程通过转移对象所有权的方式向Worker线程发送消息。 **系统能力：** SystemCapability.Utils.Lang @@ -170,8 +170,8 @@ postMessage(message: Object, transfer: ArrayBuffer[]): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------- | ---- | ------------------------------------------------------------ | -| message | Object | 是 | 发送至Worker的数据。 | -| transfer | ArrayBuffer[] | 是 | 可传递 ArrayBuffer 的实例对象，数组中不可传入null。 | +| message | Object | 是 | 发送至Worker的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 | +| transfer | ArrayBuffer[] | 是 | 表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将会变为不可用，仅在Worker线程中可用，数组不可传入null。 | **错误码：** @@ -195,7 +195,7 @@ workerInstance.postMessage(buffer, [buffer]); postMessage(message: Object, options?: PostMessageOptions): void -向Worker线程发送数据，数据类型必须是序列化所支持的类型。序列化支持类型见其他说明。 +宿主线程通过转移对象所有权或者拷贝数据的方式向Worker线程发送消息。 **系统能力：** SystemCapability.Utils.Lang @@ -203,8 +203,8 @@ postMessage(message: Object, options?: PostMessageOptions): void | 参数名 | 类型 | 必填 | 说明 | | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| message | Object | 是 | 发送至Worker的数据。 | -| options | [PostMessageOptions](#postmessageoptions) | 否 | 可传输对象是 ArrayBuffer 的实例对象。若不填入该参数，默认设置为 undefined。| +| message | Object | 是 | 发送至Worker的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 | +| options | [PostMessageOptions](#postmessageoptions) | 否 | 当填入该参数时，与传入ArrayBuffer[]的作用一致，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将会变为不可用，仅在Worker线程中可用。
若不填入该参数，默认设置为 undefined，通过拷贝数据的方式传输信息到Worker线程。 | **错误码：** @@ -848,16 +848,16 @@ Worker线程用于与宿主线程通信的类，通过postMessage接口发送消 postMessage(messageObject: Object, transfer: ArrayBuffer[]): void; -Worker线程向宿主线程发送消息。 +Worker线程通过转移对象所有权的方式向宿主线程发送消息。 **系统能力：** SystemCapability.Utils.Lang **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------- | ---- | ------------------------------------------------------- | -| message | Object | 是 | 发送至宿主线程的数据。 | -| transfer | ArrayBuffer[] | 是 | 可传输对象是ArrayBuffer的实例对象，数组中不可传入null。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------- | ---- | ------------------------------------------------------------ | +| message | Object | 是 | 发送至宿主线程的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 | +| transfer | ArrayBuffer[] | 是 | 表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用，数组不可传入null。 | **错误码：** @@ -896,7 +896,7 @@ workerPort.onmessage = function(e){ postMessage(messageObject: Object, options?: PostMessageOptions): void -Worker线程向宿主线程发送消息。 +Worker线程通过转移对象所有权或者拷贝数据的方式向宿主线程发送消息。 **系统能力：** SystemCapability.Utils.Lang @@ -904,8 +904,8 @@ Worker线程向宿主线程发送消息。 | 参数名 | 类型 | 必填 | 说明 | | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| message | Object | 是 | 发送至宿主线程的数据。 | -| options | [PostMessageOptions](#postmessageoptions) | 否 | 可传输对象是ArrayBuffer的实例对象。若不填入该参数，默认设置为 undefined。| +| message | Object | 是 | 发送至宿主线程的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 | +| options | [PostMessageOptions](#postmessageoptions) | 否 | 当填入该参数时，与传入ArrayBuffer[]的作用一致，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用。
若不填入该参数，默认设置为 undefined，通过拷贝数据的方式传输信息到宿主线程。 | **错误码：** @@ -978,7 +978,7 @@ workerPort.onmessage = function(e) { onmessage?: (this: ThreadWorkerGlobalScope, ev: MessageEvents) => void -DedicatedWorkerGlobalScope的onmessage属性表示Worker线程收到来自其宿主线程通过postMessage接口发送的消息时被调用的事件处理程序，处理程序在Worker线程中执行。 +ThreadWorkerGlobalScope的onmessage属性表示Worker线程收到来自其宿主线程通过postMessage接口发送的消息时被调用的事件处理程序，处理程序在Worker线程中执行。 **系统能力：** SystemCapability.Utils.Lang @@ -1021,7 +1021,7 @@ workerPort.onmessage = function(e) { onmessageerror?: (this: ThreadWorkerGlobalScope, ev: MessageEvents) => void -DedicatedWorkerGlobalScope的onmessageerror属性表示当Worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序，处理程序在Worker线程中执行。 +ThreadWorkerGlobalScope的onmessageerror属性表示当Worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序，处理程序在Worker线程中执行。 **系统能力：** SystemCapability.Utils.Lang @@ -1255,9 +1255,9 @@ Stage模型: ### postMessage(deprecated) -postMessage(message: Object, transfer: ArrayBuffer[]): void; +postMessage(message: Object, transfer: ArrayBuffer[]): void -向Worker线程发送数据，数据类型必须是序列化所支持的类型。序列化支持类型见其他说明。 +宿主线程通过转移对象所有权的方式向Worker线程发送消息。 > **说明：**
> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[ThreadWorker.postMessage9+](#postmessage9)替代。 @@ -1266,10 +1266,10 @@ postMessage(message: Object, transfer: ArrayBuffer[]): void; **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------- | ---- | ----------------------------------------------- | -| message | Object | 是 | 发送至Worker的数据。 | -| transfer | ArrayBuffer[] | 是 | 可转移对象是 ArrayBuffer 的实例对象。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------- | ---- | ------------------------------------------------------------ | +| message | Object | 是 | 发送至Worker的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 | +| transfer | ArrayBuffer[] | 是 | 表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将会变为不可用，仅在Worker线程中可用，数组不可传入null。 | **示例：** @@ -1284,7 +1284,7 @@ workerInstance.postMessage(buffer, [buffer]); postMessage(message: Object, options?: PostMessageOptions): void -向Worker线程发送数据，数据类型必须是序列化所支持的类型。序列化支持类型见其他说明。 +宿主线程通过转移对象所有权或者拷贝数据的方式向Worker线程发送消息。 > **说明：**
> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[ThreadWorker.postMessage9+](#postmessage9-1)替代。 @@ -1295,8 +1295,8 @@ postMessage(message: Object, options?: PostMessageOptions): void | 参数名 | 类型 | 必填 | 说明 | | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| message | Object | 是 | 发送至Worker的数据。 | -| options | [PostMessageOptions](#postmessageoptions) | 否 | 可传输对象是 ArrayBuffer 的实例对象。若不填入该参数，默认设置为 undefined。| +| message | Object | 是 | 发送至Worker的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 | +| options | [PostMessageOptions](#postmessageoptions) | 否 | 当填入该参数时，与传入ArrayBuffer[]的作用一致，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将会变为不可用，仅在Worker线程中可用。
若不填入该参数，默认设置为 undefined，通过拷贝数据的方式传输信息到Worker线程。 | **示例：** @@ -1695,7 +1695,7 @@ Worker线程用于与宿主线程通信的类，通过postMessage接口发送消 postMessage(messageObject: Object, transfer: Transferable[]): void; -Worker线程向宿主线程发送消息。 +Worker线程通过转移对象所有权的方式向宿主线程发送消息。 > **说明：**
> 此接口暂不支持使用，从API version 9 开始废弃，建议使用[ThreadWorkerGlobalScope9+.postMessage9+](#postmessage9-2)替代。 @@ -1706,14 +1706,14 @@ Worker线程向宿主线程发送消息。 | 参数名 | 类型 | 必填 | 说明 | | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| messageObject | Object | 是 | 发送至宿主线程的数据。 | +| messageObject | Object | 是 | 发送至宿主线程的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 | | transfer| Transferable[] | 是 | 暂不支持该参数类型。 | ### postMessage9+ postMessage(messageObject: Object, transfer: ArrayBuffer[]): void; -Worker线程向宿主线程发送消息。 +Worker线程通过转移对象所有权的方式向宿主线程发送消息。 > **说明：**
> DedicatedWorkerGlobalScope类自API version 9 开始废弃，本接口建议使用[ThreadWorkerGlobalScope9+.postMessage9+](#postmessage9-2)替代。 @@ -1722,10 +1722,10 @@ Worker线程向宿主线程发送消息。 **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------- | ---- | ----------------------------------------------------- | -| message | Object | 是 | 发送至宿主线程的数据。 | -| transfer | ArrayBuffer[] | 是 | 可传输对象是ArrayBuffer的实例对象，数组不可传入null。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------- | ---- | ------------------------------------------------------------ | +| message | Object | 是 | 发送至宿主线程的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 | +| transfer | ArrayBuffer[] | 是 | 表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用，数组不可传入null。 | **示例：** @@ -1754,7 +1754,7 @@ parentPort.onmessage = function(e){ postMessage(messageObject: Object, options?: PostMessageOptions): void -Worker线程向宿主线程发送消息。 +Worker线程通过转移对象所有权或者拷贝数据的方式向宿主线程发送消息。 > **说明：**
> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[ThreadWorkerGlobalScope9+.postMessage9+](#postmessage9-3)替代。 @@ -1765,8 +1765,8 @@ Worker线程向宿主线程发送消息。 | 参数名 | 类型 | 必填 | 说明 | | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| message | Object | 是 | 发送至宿主线程的数据。 | -| options | [PostMessageOptions](#postmessageoptions) | 否 | 可传输对象是ArrayBuffer的实例对象。若不填入该参数，默认设置为 undefined。| +| message | Object | 是 | 发送至宿主线程的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 | +| options | [PostMessageOptions](#postmessageoptions) | 否 | 当填入该参数时，与传入ArrayBuffer[]的作用一致，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用。
若不填入该参数，默认设置为 undefined，通过拷贝数据的方式传输信息到宿主线程。 | **示例：** @@ -1891,7 +1891,7 @@ parentPort.onmessageerror = function(e) { ## PostMessageOptions -明确数据传递过程中需要转移所有权对象的类，传递所有权的对象必须是ArrayBuffer。 +明确数据传递过程中需要转移所有权对象的类，传递所有权的对象必须是ArrayBuffer，发送它的上下文中将会变为不可用，仅在接收方可用。 **系统能力：** SystemCapability.Utils.Lang @@ -2094,14 +2094,15 @@ Worker基于Actor并发模型实现。在Worker的交互流程中，JS主线程 Actor并发模型的交互原理：各个Actor并发地处理主线程任务，每个Actor内部都有一个消息队列及单线程执行模块，消息队列负责接收主线程及其他Actor的请求，单线程执行模块则负责串行地处理请求、向其他Actor发送请求以及创建新的Actor。由于Actor采用的是异步方式，各个Actor之间相互隔离没有数据竞争，因此Actor可以高并发运行。 ### 注意事项 -- Worker存在数量限制，当前支持最多同时存在7个Worker。 +- Worker存在数量限制，当前支持最多同时存在8个Worker。 - 在API version 8及之前的版本，当Worker数量超出限制时，会抛出错误Error "Too many workers, the number of workers exceeds the maximum."。 -- 从API version 9开始，当Worker数量超出限制时，会抛出错误BusinessError "Worker initialization failure, the number of workers exceeds the maximum"。 +- 从API version 9开始，当Worker数量超出限制时，会抛出错误BusinessError "Worker initialization failure, the number of workers exceeds the maximum."。 - 主动销毁Worker可以调用新创建Worker对象的terminate()或parentPort.close()方法。 - 自API version 9版本开始，若Worker处于已经销毁或正在销毁等非运行状态时，调用其功能接口，会抛出相应的BusinessError。 - Worker的创建和销毁耗费性能，建议管理已创建的Worker并重复使用。 - 创建Worker工程时，new worker.Worker构造函数和new worker.ThreadWorker构造函数不能同时使用，否则将导致工程中Worker的功能异常。自API version 9版本开始，建议使用[new worker.ThreadWorker](#constructor9)构造函数，在API version 8及之前的版本，建议使用[new worker.Worker](#constructordeprecated)构造函数。 - 创建Worker工程时，在Worker线程的文件中（比如本文中worker.ts）不能导入任何有关构建UI的方法（比如ets文件等），否则会导致Worker的功能失效。排查方式：解压生成的Hap包，在创建Worker线程的文件目录中找到"worker.js"，全局搜索"View"关键字。如果存在该关键字，说明在worker.js中打包进去了构建UI的方法，会导致Worker的功能失效，建议在创建Worker线程的文件中修改 "import “xxx” from src"中src的目录层级。 +- 线程间通信时传递的数据量最大限制为16M。 ## 完整示例 > **说明：**
-- GitLab