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 occur, 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. For details about the code implementation, see [Transmitting Large Data Across Concurrent Instances](sendable-guide.md#transmitting-large-data-across-concurrent-instances). 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- 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- You can also customize Native Sendable objects. For details, see [Multithreaded Operations with Custom Native Sendable Objects](napi-define-sendable-object.md). 91 92> **NOTE** 93> 94> - 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. 95> 96> - 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. 97 98 99## Implementation Principle of Sendable 100 101To 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. 102 103 104The 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. 105 106Relationship between the shared heap and local heap 107 108 109 110The 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. 111 112 113## \@Sendable Decorator 114 115The \@Sendable decorator declares and verifies Sendable classes and functions. 116 117| \@Sendable Decorator| Description| 118| -------- | -------- | 119| Parameters| None.| 120| Usage restrictions| This decorator can be used only in .ets files of the stage model.| 121| Supported function types| Only regular functions and async functions can be decorated by @Sendable.| 122| Class inheritance restrictions| Sendable classes can only inherit from other Sendable classes. Regular classes cannot inherit from Sendable classes.| 123| Property type restrictions| 1. The following types are supported: string, number, boolean, bigint, null, undefined, Sendable class, collections, ArkTSUtils.locks.AsyncLock, ArkTSUtils.SendableLruCache, and custom Sendable functions.<br>2. Closure variables are not allowed, except for top-level Sendable classes and functions.<br>3. Private properties defined with \# are not supported; use **private** instead.<br>4. Computed properties are not supported.| 124| Other property restrictions| 1. Member properties must be initialized explicitly. The exclamation mark (!) cannot be used.<br>2. 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| 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. In API version 18 and later versions, variables exported from the current file can be accessed.| 126| 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.| 127 128The following is an example of using the decorator on a class: 129 130```ts 131@Sendable 132class SendableTestClass { 133 desc: string = "sendable: this is SendableTestClass "; 134 num: number = 5; 135 printName() { 136 console.info("sendable: SendableTestClass desc is: " + this.desc); 137 } 138 get getNum(): number { 139 return this.num; 140 } 141} 142``` 143<!-- @[example_modify_class](https://gitee.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/ArkTsConcurrent/ConcurrentThreadCommunication/InterThreadCommunicationObjects/SendableObject/SendableObjectIntroduction/class/Index.ets) --> 144 145The following is an example of using the decorator on a function: 146 147```ts 148@Sendable 149type SendableFuncType = () => void; 150 151@Sendable 152class TopLevelSendableClass { 153 num: number = 1; 154 PrintNum() { 155 console.info("Top level sendable class"); 156 } 157} 158 159@Sendable 160function TopLevelSendableFunction() { 161 console.info("Top level sendable function"); 162} 163 164@Sendable 165function SendableTestFunction() { 166 const topClass = new TopLevelSendableClass(); // Top-level Sendable class. 167 topClass.PrintNum(); 168 TopLevelSendableFunction(); // Top-level Sendable function. 169 console.info("Sendable test function"); 170} 171 172@Sendable 173class SendableTestClass { 174 constructor(func: SendableFuncType) { 175 this.callback = func; 176 } 177 callback: SendableFuncType; // Top-level Sendable function. 178 179 CallSendableFunc() { 180 SendableTestFunction(); // Top-level Sendable function. 181 } 182} 183 184let sendableClass = new SendableTestClass(SendableTestFunction); 185sendableClass.callback(); 186sendableClass.CallSendableFunc(); 187``` 188<!-- @[example_modify_function](https://gitee.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/ArkTsConcurrent/ConcurrentThreadCommunication/InterThreadCommunicationObjects/SendableObject/SendableObjectIntroduction/entry/src/main/ets/managers/functionusage.ets) --> 189
