1# Sendable Object Overview
2
3On the traditional JS engine, there is only one way to optimize the concurrent communication overhead of objects. That is, the implementation is moved to the Native side, and the concurrent communication overhead is reduced through the transferable object (transferabled-object.md) transfer or sharing mode. However, developers still have the requirement for concurrent communication of a large number of objects. This problem has not been solved in the JS engine implementation in the industry.
4
5ArkTS provides the Sendable object type to solve the preceding problem through reference transfer during concurrent communication.
6
7The Sendable object can be shared. It points to the same JS object across threads. If the Sendable object contains JS or Native content, it can be directly shared. If the bottom layer is implemented by Native, thread security must be considered. The following figure shows the communication process.
8
9![sendable](figures/sendable.png)
10
11Unlike other ArkTS objects, data objects that comply with the Sendable protocol must be of a fixed type at run time.
12
13When multiple concurrent instances attempt to update Sendable data at the same time, data contention occurs, for example, multi-thread operations of [ArkTS shared container](arkts-collections-introduction.md). Therefore, ArkTS provides the asynchronous lock (arkts-async-lock-introduction.md) mechanism to avoid data competition between different concurrent instances. In addition, you can use the object freezing interface (sendable-freeze.md) to freeze an object and change it to a read-only object. In this way, you do not need to consider data competition.
14
15The Sendable object provides efficient communication between concurrent instances, that is, the reference transfer capability. It is applicable to scenarios where developers customize large objects that require inter-thread communication. For example, a sub-thread reads data from the database and returns the data to the host thread.
16
17## Basic Concepts
18
19### Sendable Protocol
20
21The Sendable protocol defines the sendable object system and its specifications of ArkTS. Data that complies with the Sendable protocol (hereinafter referred to as Sendable objects) can be transferred between ArkTS concurrent instances.
22
23By default, sendable data is passed by reference between ArkTS concurrent instances (including the main thread and the worker thread of TaskPool or Worker). 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) without any necessary method or property. **ISendable** is the parent type of all sendable types except null and undefined. **ISendable** is mainly used when you want to customize the sendable data struct. 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 the sendable class.
34
35A sendable class must meet the following requirements:
36
371. This function is available only when the [@Sendable decorator](#sendable-decorator) is marked.
38
392. The Sendable constraints must be met. For details, see [Sendable Usage Rules](sendable-constraints.md).
40
41### Sendable Function
42
43> **NOTE**
44>
45> - Since API version 12, the @Sendable decorator can be used to verify the sendable function.
46>
47> - To use a sendable function in API version 12, you must configure "compatibleSdkVersionStage": "beta3" in the project. Otherwise, the function 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
49A sendable function must meet the following requirements:
50
511. This function is available only when the [@Sendable decorator](#sendable-decorator) is marked.
52
532. The Sendable constraints must be met. For details, see [Sendable Usage Rules](sendable-constraints.md).
54
55### Sendable Interface
56
57A sendable interface must meet the following requirements:
58
591. Be [ISendable](#isendable) or inherit from [ISendable](#isendable).
60
612. The Sendable constraints must be met. For details, see [Sendable Usage Rules](sendable-constraints.md).
62
63### Sendable Data Types
64
65- All basic ArkTS data types: boolean, number, string, bigint, null, and undefined.
66
67- [Container type data](arkts-collections-introduction.md) defined in the ArkTS language standard library ([@arkts.collections](../reference/apis-arkts/js-apis-arkts-collections.md) must be explicitly introduced).
68
69- [Asynchronous lock object](arkts-async-lock-introduction.md) defined in the ArkTS language standard library ([@arkts.utils](../reference/apis-arkts/js-apis-arkts-utils.md) must be explicitly introduced).
70
71- Interfaces that inherit [ISendable](#isendable).
72
73- Class labeled with the [@Sendable decorator](#sendable-decorator).
74
75- Function labeled with the [@Sendable decorator](#sendable-decorator).
76
77- Sendable System Objects
78  - [Sendable User Preferences](../reference/apis-arkdata/js-apis-data-sendablePreferences.md)
79  - [Sendable Color Space Management](../reference/apis-arkgraphics2d/js-apis-sendableColorSpaceManager.md)
80  - [Sendable Object-based Image Processing](../reference/apis-image-kit/js-apis-sendableImage.md)
81  - [Resource Management](../reference/apis-localization-kit/js-apis-sendable-resource-manager.md)
82  - [SendableContext Object Management](../reference/apis-ability-kit/js-apis-app-ability-sendableContextManager.md)
83
84- Elements whose union type data is of the sendable type.
85
86> **NOTE**
87>
88> - The transfer of JS built-in objects between concurrent instances complies with the structured clone algorithm. The cross-thread behavior is copy transfer. Therefore, the instance of a JS built-in object is not of the sendable type.
89>
90> - Object literals and array literals are passed between concurrent instances in compliance with the structured clone algorithm, and the semantics is passed by copy. Therefore, object literals and array literals are not of the sendable type.
91
92
93## Implementation Principle of the Sendable Function
94
95To implement reference transfer of [Sendable data](#sendable-data-types) between different concurrent instances, the Sendable shared object is allocated in the shared heap to implement memory sharing across concurrent instances.
96
97The shared heap is a process-level heap space. Different from the local heap of a VM, the local heap can be accessed only by a single concurrent instance, while the shared heap can be accessed by all threads. The cross-thread behavior of a Sendable shared object is reference passing. Therefore, the Sendable may be referenced by multiple concurrent instances. Whether the Sendable shared object is alive depends on whether the objects of all concurrent instances have references to the Sendable shared object.
98
99Relationship between SharedHeap and LocalHeap
100
101![image_0000002001521153](figures/image_0000002001521153.png)
102
103The LocalHeap of each concurrent instance is isolated. The SharedHeap is a process-level heap and can be referenced by all concurrent instances. However, SharedHeap cannot reference objects in LocalHeap.
104
105
106## @Sendable Decorator
107
108Declare and verify the Sendable class and Sendable function.
109
110| @Sendable decorator| Description|
111| -------- | -------- |
112| Decorator parameters| None.|
113| Use scenario restrictions| The decorator can be used only in projects of the stage model. It can be used only in .ets files.|
114| Restrictions for decorated function types| Only common functions and async functions can be decorated by @Sendable.|
115| Inheritance relationship restrictions for decorated classes| A sendable class can inherit only from another sendable class. A common class cannot inherit from a sendable class.|
116| Property type restrictions for decorated objects| 1. The following types are supported: string, number, boolean, bigint, null, undefined, Sendable class, collections.Array, collections.Map, and collections.Set.<br>2. Closure variables are not allowed.<br>3. Private attributes cannot be defined using \#. Use private instead.<br>4. Computed properties are not supported.|
117| Other property restrictions for decorated objects| Member properties must be initialized explicitly. They cannot be followed by exclamation marks (!).|
118| Restrictions on method parameters in decorated functions or class objects| Local variables, input parameters, and variables imported through **import** are supported. Do not use closure variables, except the sendable class and sendable function defined at the top layer.|
119| Restrictions on the Sendable Class and Sendable Function| Properties cannot be added or deleted, but can be modified. The property types before and after the modification must be the same. Methods cannot be modified.|
120| Use scenario| 1. Use the class method or Sendable function in TaskPool or Worker.<br>2. The sendable type is used when a large amount of data needs to be transmitted.|
121
122The following is an example of using a decorator to modify a class:
123
124```ts
125@Sendable
126class SendableTestClass {
127  desc: string = "sendable: this is SendableTestClass ";
128  num: number = 5;
129  printName() {
130    console.info("sendable: SendableTestClass desc is: " + this.desc);
131  }
132  get getNum(): number {
133    return this.num;
134  }
135}
136```
137
138The following is an example of using the decorator to decorate a function:
139
140```ts
141@Sendable
142type SendableFuncType = () => void;
143
144@Sendable
145class TopLevelSendableClass {
146  num: number = 1;
147  PrintNum() {
148    console.info("Top level sendable class");
149  }
150}
151
152@Sendable
153function TopLevelSendableFunction() {
154  console.info("Top level sendable function");
155}
156
157@Sendable
158function SendableTestFunction() {
159  const topClass = new TopLevelSendableClass (); // Top-level sendable class.
160  topClass.PrintNum();
161  TopLevelSendableFunction (); // Top-level sendable function.
162  console.info("Sendable test function");
163}
164
165@Sendable
166class SendableTestClass {
167  constructor(func: SendableFuncType) {
168    this.callback = func;
169  }
170  callback: SendableFuncType; // Top-level sendable function.
171
172  CallSendableFunc() {
173    SendableTestFunction (); // Top-level sendable function.
174  }
175}
176
177let sendableClass = new SendableTestClass(SendableTestFunction);
178sendableClass.callback();
179sendableClass.CallSendableFunc();
180```
181