1# Shared Container 2 3## ArkTS Collections 4 5ArkTS shared containers ([@arkts.collections (ArkTS Collections)](../reference/apis-arkts/js-apis-arkts-collections.md)) are designed for high-performance data transmission between concurrent tasks. They offer similar functionality to the containers defined in the ECMAScript 262 specification but with some key differences, which are outlined in the [Behavior Differences Between Shared Container APIs and Native APIs](#behavior-differences-between-shared-container-apis-and-native-apis). 6 7By default, ArkTS shared containers are passed by reference, allowing multiple concurrent tasks to manipulate the same container instance. They also support pass-by-copy, where each concurrent task holds an ArkTS container instance. 8 9ArkTS shared containers are not thread-safe and employ a fail-fast mechanism to prevent concurrent structural modifications, which would otherwise trigger exceptions. When modifying container properties, you must use the [asynchronous lock](arkts-async-lock-introduction.md) mechanism to ensure safe access. 10 11The ArkTS shared containers include the following types: [Array](../reference/apis-arkts/js-apis-arkts-collections.md#collectionsarray), [Map](../reference/apis-arkts/js-apis-arkts-collections.md#collectionsmap), [Set](../reference/apis-arkts/js-apis-arkts-collections.md#collectionsset), [TypedArray](../reference/apis-arkts/js-apis-arkts-collections.md#collectionstypedarray) (Int8Array, Uint8Array, Int16Array, Uint16Array, Int32Array, Uint32Array, Uint8ClampedArray, and Float32Array), and [ArrayBuffer](../reference/apis-arkts/js-apis-arkts-collections.md#collectionsarraybuffer). For details, see [@arkts.collections (ArkTS Collections)](../reference/apis-arkts/js-apis-arkts-collections.md). 12 13The following is an example of using the collection: 14 15```ts 16import { ArkTSUtils, collections, taskpool } from '@kit.ArkTS'; 17 18@Concurrent 19async function add(arr: collections.Array<number>, lock: ArkTSUtils.locks.AsyncLock) { 20 await lock.lockAsync(() => { // Without the asynchronous lock, the task will fail due to data race conflicts. 21 arr[0]++; 22 }) 23} 24 25@Entry 26@Component 27struct Index { 28 @State message: string = 'Hello World'; 29 30 build() { 31 RelativeContainer() { 32 Text(this.message) 33 .id('HelloWorld') 34 .fontSize(50) 35 .fontWeight(FontWeight.Bold) 36 .alignRules({ 37 center: { anchor: '__container__', align: VerticalAlign.Center }, 38 middle: { anchor: '__container__', align: HorizontalAlign.Center } 39 }) 40 .onClick(() => { 41 let taskGroup = new taskpool.TaskGroup(); 42 let lock = new ArkTSUtils.locks.AsyncLock(); 43 let arr = collections.Array.create<number>(1, 0); 44 let count = 1000; 45 while (count--) { 46 taskGroup.addTask(add, arr, lock); 47 } 48 taskpool.execute(taskGroup).then(() => { 49 console.info(`Return success: ${arr[0]} === ${count}`); 50 }).catch((e: Error) => { 51 console.error("Return error."); 52 }) 53 }) 54 } 55 .height('100%') 56 .width('100%') 57 } 58} 59``` 60 61## Behavior Differences Between Shared Container APIs and Native APIs 62 63ArkTS provides shared containers for Sendable data, with some behavior differences when compared with native APIs. These differences are detailed below. 64 65> **NOTE** 66> 67> ArkTS shared containers have different types from native ECMAScript containers. Therefore, if the native **isArray()** method is used on a **collections.Array instance** object, **false** is returned. 68 69### Array 70 71Native Array containers can be converted into ArkTS Array containers using the [collections.Array.from](../reference/apis-arkts/js-apis-arkts-collections.md#from) method, and ArkTS Array containers can be converted into native Array containers using the native **from** method. 72 73| Native API| ArkTS Collections API| Behavior Difference Exists| Different Behavior in ArkTS Collections| 74| -------- | -------- | -------- | -------- | 75| length: number | readonly length: number | Yes| To prevent the spread of **undefined**, it is not allowed to set **length**.| 76| new(arrayLength ?: number): any[] | static create(arrayLength: number, initialValue: T): Array | Yes| To prevent the spread of **undefined**, a constructor must be provided with an initial value.| 77| new <T>(arrayLength: number): T[] | constructor() | No| / | 78| new <T>(...items: T[]): T[] | constructor(first: T, ...left: T[]) | Yes| To prevent the spread of **undefined**, a constructor must be provided with an initial value. In inheritance scenarios, this constructor cannot be called to construct an object.| 79| from<T>(arrayLike: ArrayLike<T>): T[] | static from<T>(arrayLike: ArrayLike<T>): Array<T> | No| / | 80| pop(): T \| undefined | pop(): T \| undefined | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 81| push(...items: T[]): number | push(...items: T[]): number | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 82| concat(...items: ConcatArray<T>[]): T[] | concat(...items: ConcatArray<T>[]): Array<T> | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 83| concat(...items: (T \| ConcatArray<T>)[]): T[] | concat(...items: ConcatArray<T>[]): Array<T> | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 84| join(separator?: string): string | join(separator?: string): string | No| / | 85| shift(): T \| undefined | shift(): T \| undefined | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 86| slice(start?: number, end?: number): T[] | slice(start?: number, end?: number): Array<T> | No| / | 87| sort(compareFn?: (a: T, b: T) => number): this | sort(compareFn?: (a: T, b: T) => number): Array<T> | Yes| 1. It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.<br>2. In inheritance scenarios, the actual type of the return value cannot be obtained.| 88| unshift(...items: T[]): number | unshift(...items: T[]): number | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 89| indexOf(searchElement: T, fromIndex?: number): number | indexOf(searchElement: T, fromIndex?: number): number | No| / | 90| forEach(callbackfn: (value: T, index: number, array: T[]) => void, thisArg?: any): void | forEach(callbackFn: (value: T, index: number, array: Array<T>) => void): void | Yes| ArkTS does not support **this**. As a result, the **thisArg** parameter is not supported.| 91| map<U>(callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any): U[] | map<U>(callbackFn: (value: T, index: number, array: Array<T>) => U): Array<U> | Yes| ArkTS does not support **this**. As a result, the **thisArg** parameter is not supported.| 92| filter(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): T[] | filter(predicate: (value: T, index: number, array: Array<T>) => boolean): Array<T> | Yes| ArkTS does not support **this**. As a result, the **thisArg** parameter is not supported.| 93| reduce(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T): T | reduce(callbackFn: (previousValue: T, currentValue: T, currentIndex: number, array: Array<T>) => T): T | No| / | 94| reduce<U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U): U | reduce<U>(callbackFn: (previousValue: U, currentValue: T, currentIndex: number, array: Array<T>) => U, initialValue: U): U | No| / | 95| [n: number]: T | [index: number]: T | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 96| findIndex(predicate: (value: T, index: number, obj: T[]) => unknown, thisArg?: any): number | findIndex(predicate: (value: T, index: number, obj: Array<T>) => boolean): number | Yes| ArkTS does not support **this**. As a result, the **thisArg** parameter is not supported.| 97| fill(value: T, start?: number, end?: number): this | fill(value: T, start?: number, end?: number): Array<T> | Yes| 1. It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.<br>2. In inheritance scenarios, the actual type of the return value cannot be obtained.| 98| entries(): IterableIterator<[number, T]> | entries(): IterableIterator<[number, T]> | No| / | 99| keys(): IterableIterator<number> | keys(): IterableIterator<number> | No| / | 100| values(): IterableIterator<T> | values(): IterableIterator<T> | No| / | 101| includes(searchElement: T, fromIndex?: number): boolean | includes(searchElement: T, fromIndex?: number): boolean | No| / | 102| at(index: number): T \| undefined | at(index: number): T \| undefined | No| / | 103 104### ArrayBuffer 105 106| Native API| ArkTS Collections API| Behavior Difference Exists| Different Behavior in ArkTS Collections| 107| -------- | -------- | -------- | -------- | 108| readonly byteLength: number | readonly byteLength: number | No| / | 109| slice(begin: number, end?: number): ArrayBuffer | slice(begin: number, end?: number): ArrayBuffer | No| / | 110| new(byteLength: number): ArrayBuffer | constructor(byteLength: number) | No| / | 111 112### TypedArray (Int8Array Used as an Example) 113 114Native TypedArray containers can be converted into ArkTS TypedArray containers using the [collections.TypedArray.from](../reference/apis-arkts/js-apis-arkts-collections.md#from-1) method, and ArkTS TypedArray containers can be converted into native TypedArray containers using the native **from** method. 115 116| Native API| ArkTS Collections API| Behavior Difference Exists| Different Behavior in ArkTS Collections| 117| -------- | -------- | -------- | -------- | 118| readonly buffer: ArrayBufferLike | readonly buffer: ArrayBuffer | No| / | 119| readonly byteLength: number | readonly byteLength: number | No| / | 120| readonly byteOffset: number | readonly byteOffset: number | No| / | 121| readonly length: number | readonly length: number | No| / | 122| readonly BYTES_PER_ELEMENT: number | static readonly BYTES_PER_ELEMENT: number | No| / | 123| copyWithin(target: number, start: number, end?: number): this | copyWithin(target: number, start: number, end?: number): Int8Array | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 124| every(predicate: (value: number, index: number, array: Int8Array) => unknown, thisArg?: any): boolean | every(predicate: TypedArrayPredicateFn<number, Int8Array>): boolean | Yes| 1. It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.<br>2. ArkTS does not support **this**. As a result, the **thisArg** parameter is not supported.| 125| fill(value: number, start?: number, end?: number): this | fill(value: number, start?: number, end?: number): Int8Array | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 126| filter(predicate: (value: number, index: number, array: Int8Array) => any, thisArg?: any): Int8Array | filter(predicate: TypedArrayPredicateFn<number, Int8Array>): Int8Array | Yes| 1. It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.<br>2. ArkTS does not support **this**. As a result, the **thisArg** parameter is not supported.| 127| find(predicate: (value: number, index: number, obj: Int8Array) => boolean, thisArg?: any): number \| undefined | find(predicate: TypedArrayPredicateFn<number, Int8Array>): number \| undefined | Yes| 1. It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.<br>2. ArkTS does not support **this**. As a result, the **thisArg** parameter is not supported.| 128| findIndex(predicate: (value: number, index: number, obj: Int8Array) => boolean, thisArg?: any): number | findIndex(predicate: TypedArrayPredicateFn<number, Int8Array>): number | Yes| ArkTS does not support **this**. As a result, the **thisArg** parameter is not supported.| 129| forEach(callbackfn: (value: number, index: number, array: Int8Array) => void, thisArg?: any): void | forEach(callbackFn: (value: number, index: number, array: Int8Array) => void): void | Yes| 1. It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.<br>2. ArkTS does not support **this**. As a result, the **thisArg** parameter is not supported.| 130| indexOf(searchElement: number, fromIndex?: number): number | indexOf(searchElement: number, fromIndex?: number): number | No| / | 131| join(separator?: string): string | join(separator?: string): string | No| / | 132| map(callbackfn: (value: number, index: number, array: Int8Array) => number, thisArg?: any): Int8Array | map(callbackFn: TypedArrayForEachCallback<number, Int8Array>): Int8Array | Yes| 1. It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.<br>2. ArkTS does not support **this**. As a result, the **thisArg** parameter is not supported.| 133| reduce(callbackfn: (previousValue: number, currentValue: number, currentIndex: number, array: Int8Array) => number): number | reduce(callbackFn: TypedArrayReduceCallback<number, number, Int8Array>): number | No| / | 134| reduce(callbackfn: (previousValue: number, currentValue: number, currentIndex: number, array: Int8Array) => number, initialValue: number): number | reduce(callbackFn: TypedArrayReduceCallback<number, number, Int8Array>, initialValue: number): number | No| / | 135| reduce<U>(callbackfn: (previousValue: U, currentValue: number, currentIndex: number, array: Int8Array) => U, initialValue: U): U | reduce<U>(callbackFn: TypedArrayReduceCallback<U, number, Int8Array>, initialValue: U): U | No| / | 136| reverse(): Int8Array | reverse(): Int8Array | No| / | 137| set(array: ArrayLike<number>, offset?: number): void | set(array: ArrayLike<number>, offset?: number): void | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 138| slice(start?: number, end?: number): Int8Array | slice(start?: number, end?: number): Int8Array | No| / | 139| some(predicate: (value: number, index: number, array: Int8Array) => unknown, thisArg?: any): boolean | some(predicate: TypedArrayPredicateFn<number, Int8Array>): boolean | Yes| ArkTS does not support **this**. As a result, the **thisArg** parameter is not supported.| 140| sort(compareFn?: (a: number, b: number) => number): this | sort(compareFn?: TypedArrayCompareFn<number>): Int8Array | Yes| 1. It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.<br>2. In inheritance scenarios, the actual type of the return value cannot be obtained.| 141| subarray(begin?: number, end?: number): Int8Array | subarray(begin?: number, end?: number): Int8Array | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 142| [index: number]: number | [index: number]: number | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 143| entries(): IterableIterator<[number, number]> | entries(): IterableIterator<[number, number]> | No| / | 144| keys(): IterableIterator<number> | keys(): IterableIterator<number> | No| / | 145| values(): IterableIterator<number> | values(): IterableIterator<number> | No| / | 146| includes(searchElement: number, fromIndex?: number): boolean | includes(searchElement: number, fromIndex?: number): boolean | No| / | 147| at(index: number): number \| undefined | at(index: number): number \| undefined | No| / | 148| new(length: number): Int8Array | constructor(length: number) | No| / | 149| new(array: ArrayLike<number> \| ArrayBufferLike): Int8Array | constructor(array: ArrayLike<number> \| ArrayBuffer) | No| / | 150| new(buffer: ArrayBufferLike, byteOffset?: number, length?: number): Int8Array | constructor(buffer: ArrayBuffer, byteOffset?: number, length?: number) | No| / | 151| from(arrayLike: ArrayLike<number>): Int8Array | static from(arrayLike: ArrayLike<number>): Int8Array | No| / | 152| from<T>(arrayLike: ArrayLike<T>, mapfn: (v: T, k: number) => number, thisArg?: any): Int8Array | static from<T>(arrayLike: ArrayLike<T>, mapFn: TypedArrayFromMapFn<T, number>): Int8Array | Yes| ArkTS does not support **this**. As a result, the **thisArg** parameter is not supported.| 153| from(arrayLike: Iterable<number>, mapfn?: (v: number, k: number) => number, thisArg?: any): Int8Array | static from(arrayLike: Iterable<number>, mapFn?: TypedArrayFromMapFn<number, number>): Int8Array | Yes| ArkTS does not support **this**. As a result, the **thisArg** parameter is not supported.| 154 155### Map 156 157| Native API| ArkTS Collections API| Behavior Difference Exists| Different Behavior in ArkTS Collections| 158| -------- | -------- | -------- | -------- | 159| readonly size: number | readonly size: number | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 160| clear(): void | clear(): void | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 161| delete(key: K): boolean | delete(key: K): boolean | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 162| forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void | forEach(callbackFn: (value: V, key: K, map: Map<K, V>) => void): void | Yes| 1. It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.<br>2. ArkTS does not support **this**. As a result, the **thisArg** parameter is not supported.| 163| get(key: K): V \| undefined | get(key: K): V \| undefined | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 164| has(key: K): boolean | has(key: K): boolean | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 165| set(key: K, value: V): this | set(key: K, value: V): Map<K, V> | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 166| entries(): IterableIterator<[K, V]> | entries(): IterableIterator<[K, V]> | No| / | 167| keys(): IterableIterator<K> | keys(): IterableIterator<K> | No| / | 168| values(): IterableIterator<V> | values(): IterableIterator<V> | No| / | 169| new <K, V>(entries?: readonly (readonly [K, V])[] \| null): Map<K, V> | constructor(entries?: readonly (readonly [K, V])[] \| null) | Yes| The passed-in values of **k** and **v** during construction cannot be non-Sendable data. Otherwise, an error is reported during compilation.| 170 171### Set 172 173| Native API| ArkTS Collections API| Behavior Difference Exists| Different Behavior in ArkTS Collections| 174| -------- | -------- | -------- | -------- | 175| readonly size: number | readonly size: number | Yes| Computed property names (arkts-sendable-compated-prop-name) cannot be used in Sendable classes and interfaces.| 176| add(value: T): this | add(value: T): Set<T> | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 177| clear(): void | clear(): void | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 178| delete(value: T): boolean | delete(value: T): boolean | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 179| forEach(callbackfn: (value: T, value2: T, set: Set<T>) => void, thisArg?: any): void | forEach(callbackFn: (value: T, value2: T, set: Set<T>) => void): void | Yes| 1. It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.<br>2. ArkTS does not support **this**. As a result, the **thisArg** parameter is not supported.| 180| has(value: T): boolean | has(value: T): boolean | Yes| It is not allowed to add, delete, or modify elements during iteration or access. Otherwise, an exception is thrown.| 181| entries(): IterableIterator<[T, T]> | entries(): IterableIterator<[T, T]> | No| / | 182| keys(): IterableIterator<T> | keys(): IterableIterator<T> | No| / | 183| values(): IterableIterator<T> | values(): IterableIterator<T> | Yes| Computed property names (arkts-sendable-compated-prop-name) cannot be used in Sendable classes and interfaces.| 184| new <T = any>(values?: readonly T[] \| null): Set<T> | constructor(values?: readonly T[] \| null) | Yes| The passed-in values during construction cannot be non-Sendable data. Otherwise, an error is reported during compilation.| 185