1# Overview of Sendable Objects 2 3In 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](transferabled-object.md). However, this solution falls short of addressing the extensive demand for concurrent object communication. The issue remains unresolved in current JS engine implementations. 4 5ArkTS introduces the concept of Sendable objects, which support pass-by-reference during concurrent communication. 6 7Sendable 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. 8 9 10 11Unlike other ArkTS objects, Sendable objects must have a fixed type at runtime. 12 13When multiple concurrent instances attempt to update Sendable data at the same time, data races occurs, such as multithreaded operations on [ArkTS shared container](arkts-collections-introduction.md). To address data race issues between concurrent instances and manage the timing of multithreaded data processing, ArkTS introduces the mechanisms of [asynchronous lock](arkts-async-lock-introduction.md) and [asynchronous waiting](arkts-condition-variable-introduction.md). Additionally, objects can be frozen using the [object freezing interface](sendable-freeze.md), making them read-only and thereby eliminating the risk of data races. 14 15Sendable 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. 16 17## Basic Concepts 18 19### Sendable Protocol 20 21The 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. 22 23By 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. 24 25### ISendable 26 27The interface **ISendable** is introduced to the ArkTS common library [@arkts.lang](../reference/apis-arkts/js-apis-arkts-lang.md). 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](#sendable-decorator) is the syntax sugar for implementing ISendable. 28 29### Sendable Class 30 31> **NOTE** 32> 33> Since API version 11, the \@Sendable decorator can be used to verify Sendable classes. 34 35A Sendable class must meet the following requirements: 36 371. It must be decorated by [@Sendable](#sendable-decorator). 38 392. It must meet the Sendable constraints. For details, see [Usage Rules and Constraints for Sendable](sendable-constraints.md). 40 41### Sendable Function 42 43> **NOTE** 44> 45> - Since API version 12, the \@Sendable decorator can be used to verify Sendable functions. 46> 47> - 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](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/ide-hvigor-build-profile-V5). 48> 49> - For projects with API versions later than 12, you can directly use the \@Sendable decorator to verify Sendable functions without any other configuration. 50 51A Sendable function must meet the following requirements: 52 531. It must be decorated by [@Sendable](#sendable-decorator). 54 552. It must meet the Sendable constraints. For details, see [Usage Rules and Constraints for Sendable](sendable-constraints.md). 56 57### Sendable Interface 58 59A Sendable interface must meet the following requirements: 60 611. It must be [ISendable](#isendable) or inherit from [ISendable](#isendable). 62 632. It must meet the Sendable constraints. For details, see [Usage Rules and Constraints for Sendable](sendable-constraints.md). 64 65### Sendable Data Types 66 67- All ArkTS basic data types: boolean, number, string, bigint, null, and undefined. 68 69- [Container types](arkts-collections-introduction.md) defined in ArkTS ([@arkts.collections](../reference/apis-arkts/js-apis-arkts-collections.md) must be explicitly introduced). 70 71- [Asynchronous lock objects](arkts-async-lock-introduction.md) defined in ArkTS ([@arkts.utils](../reference/apis-arkts/js-apis-arkts-utils.md) must be explicitly introduced). 72 73- [Asynchronous waiting objects](arkts-condition-variable-introduction.md) defined in ArkTS ([@arkts.utils](../reference/apis-arkts/js-apis-arkts-utils.md) must be explicitly introduced). 74 75- Interfaces that inherit from [ISendable](#isendable). 76 77- Classes decorated by [@Sendable](#sendable-decorator). 78 79- Functions decorated by [@Sendable](#sendable-decorator). 80 81- System objects that integrate Sendable, which are as follows: 82 - [Sendable User Preferences](../reference/apis-arkdata/js-apis-data-sendablePreferences.md) 83 - [Sendable Color Space Management](../reference/apis-arkgraphics2d/js-apis-sendableColorSpaceManager.md) 84 - [Sendable Object-based Image Processing](../reference/apis-image-kit/js-apis-sendableImage.md) 85 - [Resource Management](../reference/apis-localization-kit/js-apis-sendable-resource-manager.md) 86 - [SendableContext Object Management](../reference/apis-ability-kit/js-apis-app-ability-sendableContextManager.md) 87 88- Elements whose union type data is of the Sendable type. 89 90> **NOTE** 91> 92> - 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. 93> 94> - 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. 95 96 97## Implementation Principle of Sendable 98 99To implement pass-by-reference of [Sendable data](#sendable-data-types) between different concurrent instances, Sendable objects are allocated in a shared heap to achieve memory sharing across concurrent instances. 100 101 102The 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. 103 104Relationship between the shared heap and local heap 105 106 107 108The 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. 109 110 111## \@Sendable Decorator 112 113The \@Sendable decorator declares and verifies Sendable classes and functions. 114 115| \@Sendable Decorator| Description| 116| -------- | -------- | 117| Parameters| None.| 118| Usage restrictions| It can be used only in projects of the stage model and only in .ets files.| 119| Supported function types| Only regular functions and async functions can be decorated by @Sendable.| 120| Class inheritance restrictions| Sendable classes can only inherit from other Sendable classes. Regular classes cannot inherit from Sendable classes.| 121| Property type restrictions| 1. The following types are supported: string, number, boolean, bigint, null, undefined, Sendable class, collections.Array, collections.Map, collections.Set, and ArkTSUtils.locks.AsyncLock.<br>2. Closure variables are not allowed.<br>3. Private properties defined with \# are not supported; use **private** instead.<br>4. Computed properties are not supported.| 122| Other property restrictions| Member properties must be initialized explicitly. They cannot be followed by exclamation marks (!).| 123| Parameter restrictions for decorated functions or class methods| Local variables, parameters, and variables imported through **import** are allowed. Closure variables are not allowed, except for top-level Sendable classes and functions. Since API version 18, functions or class objects decorated by @Sendable can also access variables exported from the same file.| 124| Restrictions for Sendable classes and functions| Adding or deleting properties is not allowed. Modifying properties is allowed, but the type must remain consistent before and after modification. Modifying methods is not supported.| 125| Use scenario| 1. Scenarios where class methods or Sendable functions are used in TaskPool or Worker.<br>2. Scenarios involving large amounts of object data transmission. The time required for serialization increases with the data volume. After transforming data with Sendable, the efficiency of transmitting 100 KB of data is approximately 20 times higher, and for 1 MB of data, it is about 100 times higher.| 126 127The following is an example of using the decorator on a class: 128 129```ts 130@Sendable 131class SendableTestClass { 132 desc: string = "sendable: this is SendableTestClass "; 133 num: number = 5; 134 printName() { 135 console.info("sendable: SendableTestClass desc is: " + this.desc); 136 } 137 get getNum(): number { 138 return this.num; 139 } 140} 141``` 142 143The following is an example of using the decorator on a function: 144 145```ts 146@Sendable 147type SendableFuncType = () => void; 148 149@Sendable 150class TopLevelSendableClass { 151 num: number = 1; 152 PrintNum() { 153 console.info("Top level sendable class"); 154 } 155} 156 157@Sendable 158function TopLevelSendableFunction() { 159 console.info("Top level sendable function"); 160} 161 162@Sendable 163function SendableTestFunction() { 164 const topClass = new TopLevelSendableClass(); // Top-level Sendable class. 165 topClass.PrintNum(); 166 TopLevelSendableFunction(); // Top-level Sendable function. 167 console.info("Sendable test function"); 168} 169 170@Sendable 171class SendableTestClass { 172 constructor(func: SendableFuncType) { 173 this.callback = func; 174 } 175 callback: SendableFuncType; // Top-level Sendable function. 176 177 CallSendableFunc() { 178 SendableTestFunction(); // Top-level Sendable function. 179 } 180} 181 182let sendableClass = new SendableTestClass(SendableTestFunction); 183sendableClass.callback(); 184sendableClass.CallSendableFunc(); 185``` 186
