Overview of Sendable Objects

In traditional JS engines, there is only one way to optimize the overhead of concurrent object communication: moving the implementation to the native side and reducing costs through the transfer or sharing of Transferable objects. However, this solution falls short of addressing the extensive demand for concurrent object communication. The issue remains unresolved in current JS engine implementations.

ArkTS introduces the concept of Sendable objects, which support pass-by-reference during concurrent communication.

Sendable objects are designed to be shareable across threads, maintaining a consistent reference to the same JS object before and after crossing thread boundaries. If a Sendable object contains JS or native content, it can be directly shared. However, if the underlying implementation is native, thread safety must be carefully considered. The following figure shows the communication process.

Unlike other ArkTS objects, Sendable objects must have a fixed type at runtime.

When multiple concurrent instances attempt to update Sendable data at the same time, data races occurs, such as multithreaded operations on ArkTS shared container. To address data race issues between concurrent instances and manage the timing of multithreaded data processing, ArkTS introduces the mechanisms of asynchronous lock and asynchronous waiting. Additionally, objects can be frozen using the object freezing interface, making them read-only and thereby eliminating the risk of data races.

Sendable objects offer efficient communication between concurrent instances by means of pass by reference. They are generally suitable for scenarios where large custom objects need to be transferred between threads, such as when a child thread reads data from a database and returns it to the main thread.

Basic Concepts

Sendable Protocol

The Sendable protocol defines the Sendable object system and its specifications in ArkTS. Data that complies with the Sendable protocol (referred to as Sendable objects) can be passed between concurrent instances in ArkTS.

By default, Sendable data is passed by reference between concurrent instances (including the UI main thread, TaskPool thread, and Worker thread). Pass-by-copy is also supported.

ISendable

The interface ISendable is introduced to the ArkTS common library @arkts.lang. It has no required methods or properties. ISendable is the parent type of all Sendable types except for null and undefined. ISendable is mainly used when you want to customize Sendable data structures. The class decorator @Sendable decorator is the syntax sugar for implementing ISendable.

Sendable Class

NOTE

Since API version 11, the \@Sendable decorator can be used to verify Sendable classes.

A Sendable class must meet the following requirements:

1. It must be decorated by @Sendable.

2. It must meet the Sendable constraints. For details, see Usage Rules and Constraints for Sendable.

Sendable Function

NOTE

• Since API version 12, the \@Sendable decorator can be used to verify Sendable functions.

• For projects with API version 12, to use the \@Sendable decorator to verify Sendable functions, you must configure “compatibleSdkVersionStage”: “beta3” in the project. Otherwise, the Sendable feature does not take effect. For details, see build-profile.json5.

• For projects with API versions later than 12, you can directly use the \@Sendable decorator to verify Sendable functions without any other configuration.

A Sendable function must meet the following requirements:

1. It must be decorated by @Sendable.

2. It must meet the Sendable constraints. For details, see Usage Rules and Constraints for Sendable.

Sendable Interface

A Sendable interface must meet the following requirements:

1. It must be ISendable or inherit from ISendable.

2. It must meet the Sendable constraints. For details, see Usage Rules and Constraints for Sendable.

Sendable Data Types

• All ArkTS basic data types: boolean, number, string, bigint, null, and undefined.

• Container types defined in ArkTS (@arkts.collections must be explicitly introduced).

• Asynchronous lock objects defined in ArkTS (@arkts.utils must be explicitly introduced).

• Asynchronous waiting objects defined in ArkTS (@arkts.utils must be explicitly introduced).

• Interfaces that inherit from ISendable.

• Classes decorated by @Sendable.

• Functions decorated by @Sendable.

• System objects that integrate Sendable, which are as follows:

  • Sendable User Preferences
  • Sendable Color Space Management
  • Sendable Object-based Image Processing
  • Resource Management
  • SendableContext Object Management

• Elements whose union type data is of the Sendable type.

NOTE

• Built-in JS objects are passed between concurrent instances following the structured clone algorithm, and their cross-thread behavior is pass-by-copy. Therefore, instances of JS built-in objects are not of the Sendable type.

• Object literals and array literals are also passed between concurrent instances following the structured cloning algorithm, and their cross-thread behavior is pass-by-copy. Therefore, object literals and array literals are not of the Sendable type.

Implementation Principle of Sendable

To implement pass-by-reference of Sendable data between different concurrent instances, Sendable objects are allocated in a shared heap to achieve memory sharing across concurrent instances.

The shared heap is a process-level heap space. Unlike the local heap of a virtual machine, which can only be accessed by a single concurrent instance, the shared heap can be accessed by all threads. The cross-thread behavior of a Sendable object is pass-by-reference. Therefore, a Sendable object may be referenced by multiple concurrent instances, and its liveness depends on whether any concurrent instance holds a reference to it.

Relationship between the shared heap and local heap

The local heap of each concurrent instance is isolated, whereas the shared heap is a process-level heap that can be referenced by all concurrent instances. However, the shared heap cannot reference objects in the local heap.

\@Sendable Decorator

The \@Sendable decorator declares and verifies Sendable classes and functions.

The following is an example of using the decorator on a class:

@Sendable
class SendableTestClass {
  desc: string = "sendable: this is SendableTestClass ";
  num: number = 5;
  printName() {
    console.info("sendable: SendableTestClass desc is: " + this.desc);
  }
  get getNum(): number {
    return this.num;
  }
}

The following is an example of using the decorator on a function:

@Sendable
type SendableFuncType = () => void;

@Sendable
class TopLevelSendableClass {
  num: number = 1;
  PrintNum() {
    console.info("Top level sendable class");
  }
}

@Sendable
function TopLevelSendableFunction() {
  console.info("Top level sendable function");
}

@Sendable
function SendableTestFunction() {
  const topClass = new TopLevelSendableClass(); // Top-level Sendable class.
  topClass.PrintNum();
  TopLevelSendableFunction(); // Top-level Sendable function.
  console.info("Sendable test function");
}

@Sendable
class SendableTestClass {
  constructor(func: SendableFuncType) {
    this.callback = func;
  }
  callback: SendableFuncType; // Top-level Sendable function.

  CallSendableFunc() {
    SendableTestFunction(); // Top-level Sendable function.
  }
}

let sendableClass = new SendableTestClass(SendableTestFunction);
sendableClass.callback();
sendableClass.CallSendableFunc();

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkTS

harmony 鸿蒙Configuring arkOptions in build-profile.json5

harmony 鸿蒙Asynchronous Lock

harmony 鸿蒙Ark Bytecode File Format

harmony 鸿蒙Naming Conventions for Ark Bytecode Functions

harmony 鸿蒙Ark Bytecode Fundamentals

harmony 鸿蒙Overview of Ark Bytecode

harmony 鸿蒙Shared Container

harmony 鸿蒙Asynchronous Waiting

harmony 鸿蒙ArkTS Cross-Language Interaction