智能客服
你问我答，随时在线为你解决问题
本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
此模块仅支持在ArkTS文件（文件后缀为.ets）中导入使用。
- 探索了解鸿蒙应用和多设备开发，学习如何构建应用/元服务应用形态HarmonyOS 应用One as All，All as One
元服务秒开直达 服务随行 无处不在
游戏为游戏创意玩法带来无限可能
多设备应用开发穿戴
折叠屏手机鸿蒙电脑开发者学堂视频课程Codelabs - 开发获取官方开发工具和文档等资源，将创意转化为鸿蒙应用开发工具DevEco Studio应用开发 IDE, AI Agent 和 CLI
小艺开放平台Skill 和智能体开发平台
ArkTS
ArKUI
AppGallery ConnectDevEco Testing开发资源工具下载示例代码开发文档最佳实践 - 分发通过华为应用市场发布你的应用，多渠道触达用户应用分发应用市场纯净安全的全场景应用分发平台
游戏中心
应用审核政策服务分发小艺HarmonyOS 的超级 AI 入口
智慧助手·今天
服务分发文档内容分发主题服务
内容分发文档 - 推广与变现一站式流量增长与营销变现平台推广应用推广引擎全链路应用推广与增长服务平台
鲸鸿动能广告为企业广告主提供广告营销服务
联运服务推广文档变现鲸鸿动能流量变现使能应用展示广告，实现流量变现应用内支付变现文档 - 生态合作携手伙伴共建共享鸿蒙智能终端生态伙伴 SDK一站式获取安全可靠的鸿蒙伙伴 SDK
生态服务鸿蒙应用开发、培训和人力服务
服务商伙伴中心华为终端云服务商伙伴的统一门户
伙伴入驻指南生态市场介绍，卖家和买家服务指引
廉洁政策合作伙伴诚信廉洁政策
- 支持获取客服帮助、技术支持、活动资讯等信息智能客服24小时 AI 在线自助服务，即问即答
社区问答在官方论坛提问，与开发者互动交流
在线提单提交工单，获得技术支持
开发者活动HDD 等线下活动速览及报名入口
资讯帮助指南
您当前正在浏览HarmonyOS最新文档，覆盖已发布的所有API版本，可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明。
namespace (locks)
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
本文导读
为了解决多并发实例间的数据竞争问题，ArkTS语言基础库引入了异步锁能力。为了开发者的开发效率，AsyncLock对象支持跨并发实例引用传递。
由于ArkTS语言支持异步操作，阻塞锁容易产生死锁问题，因此我们在ArkTS中仅支持异步锁（非阻塞式锁）。
使用异步锁的方法需要标记为async，调用方需要使用await等待调用结果，才能保证时序正确。因此会导致外层调用函数全部标记成async。
说明
导入模块
- import { ArkTSUtils } from '@kit.ArkTS';
AsyncLockCallback
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
type AsyncLockCallback<T> = () => T | Promise<T>
这是一个补充类型别名，表示lockAsync函数所有重载中的回调。
元服务API：从API version 12 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
属性
元服务API：从API version 12 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| name | string | 是 | 否 | 锁的名称。 |
示例：
- // 示例一：
- @Sendable
- class A {
- count_: number = 0;
- async getCount(): Promise<number> {
- let lock: ArkTSUtils.locks.AsyncLock = ArkTSUtils.locks.AsyncLock.request("lock_1");
- return lock.lockAsync(() => {
- return this.count_;
- });
- }
- async setCount(count: number) {
- let lock: ArkTSUtils.locks.AsyncLock = ArkTSUtils.locks.AsyncLock.request("lock_1");
- await lock.lockAsync(() => {
- this.count_ = count;
- });
- }
- }
-
- // 示例二：
- @Sendable
- class A {
- count_: number = 0;
- lock_: ArkTSUtils.locks.AsyncLock = new ArkTSUtils.locks.AsyncLock();
- async getCount(): Promise<number> {
- return this.lock_.lockAsync(() => {
- return this.count_;
- });
- }
- async setCount(count: number) {
- await this.lock_.lockAsync(() => {
- this.count_ = count;
- });
- }
- }
-
- @Concurrent
- async function foo(a: A) {
- await a.setCount(10);
- }
constructor
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
constructor()
默认构造函数。创建一个异步锁。
元服务API：从API version 12 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
示例：
- let lock = new ArkTSUtils.locks.AsyncLock();
request
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
static request(name: string): AsyncLock
使用指定的名称查找或创建（如果未找到）异步锁实例。
元服务API：从API version 12 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
参数：
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 按指定名称查找或创建异步锁实例。 |
返回值：
| 类型 | 说明 |
|---|---|
| AsyncLock | 返回查找到或创建后的异步锁实例。 |
示例：
- let lockName = 'isAvailableLock';
- let lock = ArkTSUtils.locks.AsyncLock.request(lockName);
query
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
static query(name: string): AsyncLockState
查询指定异步锁的信息。
元服务API：从API version 12 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
参数：
返回值：
| 类型 | 说明 |
|---|---|
| AsyncLockState | 包含状态描述的异步锁状态实例。 |
错误码：
以下错误码的详细介绍请参见语言基础类库错误码。
| 错误码ID | 错误信息 |
|---|---|
| 10200030 | The lock does not exist. |
示例：
- // 查询已存在的锁信息
- let lock = ArkTSUtils.locks.AsyncLock.request("queryTestLock");
- let state = ArkTSUtils.locks.AsyncLock.query('queryTestLock');
- let pending: ArkTSUtils.locks.AsyncLockInfo[] = state.pending;
- let held: ArkTSUtils.locks.AsyncLockInfo[] = state.held;
- // 输出当前处于pending状态的锁数量
- console.info(`Number of pending locks: ${pending.length}`);
- // 输出当前处于held状态的锁数量
- console.info(`Number of held locks: ${held.length}`);
-
- // 查询不存在的锁信息，会抛出错误信息：The lock does not exist.
- try {
- let state1 = ArkTSUtils.locks.AsyncLock.query('queryTestLock1');
- } catch (e) {
- console.error(`Error is: ${e}`);
- }
queryAll
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
static queryAll(): AsyncLockState[]
查询所有现有锁的信息。
元服务API：从API version 12 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
返回值：
| 类型 | 说明 |
|---|---|
| AsyncLockState[] | 包含锁状态信息的异步锁状态数组。 |
示例：
- // 查询已存在的锁信息
- let lock1 = ArkTSUtils.locks.AsyncLock.request("queryTestLock1");
- let lock2 = ArkTSUtils.locks.AsyncLock.request("queryTestLock2");
- let states: ArkTSUtils.locks.AsyncLockState[] = ArkTSUtils.locks.AsyncLock.queryAll();
- // 输出当前存在的锁数量
- console.info("The states size is " + states.length);
lockAsync
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
lockAsync<T>(callback: AsyncLockCallback<T>): Promise<T>
在获取的锁下执行操作。该方法首先获取锁，然后调用回调，最后释放锁。若锁已被其他任务持有，当前请求将进入等待队列，待锁释放后按顺序获取锁。回调在调用lockAsync的同一线程中以异步方式执行。
元服务API：从API version 12 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
参数：
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| callback | AsyncLockCallback<T> | 是 | 获取锁后要调用的函数。 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise<T> | 回调执行后将解决的Promise。 |
错误码：
以下错误码的详细介绍请参见语言基础类库错误码。
| 错误码ID | 错误信息 |
|---|---|
| 10200030 | The lock does not exist. |
示例：
- let lock = new ArkTSUtils.locks.AsyncLock();
- let p1 = lock.lockAsync<void>(() => {
- // 执行某些操作
- });
lockAsync
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
lockAsync<T>(callback: AsyncLockCallback<T>, mode: AsyncLockMode): Promise<T>
在获取的锁下执行操作。该方法首先获取锁，然后调用回调，最后释放锁。若锁已被其他任务持有，当前请求将进入等待队列，待锁释放后按顺序获取锁。回调在调用lockAsync的同一线程中以异步方式执行。
元服务API：从API version 12 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
参数：
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| callback | AsyncLockCallback<T> | 是 | 获取锁后要调用的函数。 |
| mode | AsyncLockMode | 是 | 锁的操作模式。 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise<T> | 回调执行后将解决的Promise。 |
错误码：
以下错误码的详细介绍请参见语言基础类库错误码。
| 错误码ID | 错误信息 |
|---|---|
| 10200030 | The lock does not exist. |
示例：
- let lock = new ArkTSUtils.locks.AsyncLock();
- let p1 = lock.lockAsync<void>(() => {
- // 执行某些操作
- }, ArkTSUtils.locks.AsyncLockMode.EXCLUSIVE);
lockAsync
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
lockAsync<T, U>(callback: AsyncLockCallback<T>, mode: AsyncLockMode, options: AsyncLockOptions<U>): Promise<T | U>
在获取的锁下执行操作。该方法首先获取锁，然后调用回调，最后释放锁。回调在调用lockAsync的同一线程中以异步方式执行。在AsyncLockOptions中可以提供一个可选的超时值。在这种情况下，如果超时前未能获取锁，lockAsync将返回被拒绝的Promise并带上一个BusinessError实例。这种情况下，错误信息将包含持有的锁和等待的锁的信息以及可能的死锁警告。
元服务API：从API version 12 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
参数：
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| callback | AsyncLockCallback<T> | 是 | 获取锁后要调用的函数。 |
| mode | AsyncLockMode | 是 | 锁的操作模式。 |
| options | AsyncLockOptions<U> | 是 | 锁的操作选项。 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise<T | U> | 回调执行后解决的Promise，或者在超时情况下被拒绝。 |
错误码：
以下错误码的详细介绍请参见语言基础类库错误码。
| 错误码ID | 错误信息 |
|---|---|
| 10200030 | The lock does not exist. |
| 10200031 | Timeout exceeded. |
示例：
- let lock = new ArkTSUtils.locks.AsyncLock();
- let options = new ArkTSUtils.locks.AsyncLockOptions<void>();
- options.timeout = 1000;
- let p: Promise<void> = lock.lockAsync<void, void>(
- () => {
- // 执行某些操作
- },
- ArkTSUtils.locks.AsyncLockMode.EXCLUSIVE,
- options
- );
AsyncLockMode
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
锁操作对应的模式枚举。
元服务API：从API version 12 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
| 名称 | 值 | 说明 |
|---|---|---|
| SHARED | 1 | 共享锁模式。如果指定了此模式，允许多个线程或并发任务同时获取锁并执行操作。多用于读操作、无数据竞争的并行任务。 |
| EXCLUSIVE | 2 | 独占锁模式。如果指定了此模式，仅允许持有锁的任务执行。 它与任何其他锁均不兼容，包括其他独占锁和共享锁。多用于写操作、数据更新、状态修改等可能产生竞争的场景。 |
示例：
- let lock = new ArkTSUtils.locks.AsyncLock();
- // shared0可获取锁并开始执行
- lock.lockAsync(async () => {
- console.info('shared0');
- await new Promise<void>((resolve) => setTimeout(resolve, 1000));
- }, ArkTSUtils.locks.AsyncLockMode.SHARED);
- // shared1可获取锁并开始执行，无需等待shared0
- lock.lockAsync(async () => {
- console.info('shared1');
- await new Promise<void>((resolve) => setTimeout(resolve, 1000));
- }, ArkTSUtils.locks.AsyncLockMode.SHARED);
- // exclusive0需等待shared0、1执行完后才可获取锁并执行
- lock.lockAsync(async () => {
- console.info('exclusive0');
- await new Promise<void>((resolve) => setTimeout(resolve, 1000));
- }, ArkTSUtils.locks.AsyncLockMode.EXCLUSIVE);
- // shared2需等待exclusive0执行完后才可获取锁并执行
- lock.lockAsync(async () => {
- console.info('shared2');
- await new Promise<void>((resolve) => setTimeout(resolve, 1000));
- }, ArkTSUtils.locks.AsyncLockMode.SHARED);
- // shared3需等待exclusive0执行完后才可获取锁并执行，无需等待shared2
- lock.lockAsync(async () => {
- console.info('shared3');
- await new Promise<void>((resolve) => setTimeout(resolve, 1000));
- }, ArkTSUtils.locks.AsyncLockMode.SHARED);
AsyncLockOptions
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
class AsyncLockOptions<T>
表示锁操作选项的类。
元服务API：从API version 12 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
constructor
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
constructor()
默认构造函数。创建一个所有属性均具有默认值的异步锁配置项实例。
元服务API：从API version 12 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
示例：
- let s: ArkTSUtils.locks.AbortSignal<string> = { aborted: false, reason: 'Aborted' };
- let options = new ArkTSUtils.locks.AsyncLockOptions<string>();
- options.isAvailable = false;
- options.signal = s;
- let lock = new ArkTSUtils.locks.AsyncLock();
- let p = lock.lockAsync<void, string>(
- () => {
- // 执行某些操作
- },
- ArkTSUtils.locks.AsyncLockMode.EXCLUSIVE,
- options,
- );
属性
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| isAvailable | boolean | 否 | 否 | 当前锁是否可用。取值为true，则只有在尚未持有锁定请求时才会授予该锁定请求；为false则表示将等待当前锁被释放。默认为 false。 |
| signal | AbortSignal<T>|null | 否 | 否 | 用于终止异步操作的对象。当signal.aborted为true时，锁请求将被丢弃；当signal.aborted为false时，请求会继续等待获取锁；当signal为null时，请求正常排队运行。默认为 null。 |
| timeout | number | 否 | 否 | 锁的超时时间，单位为毫秒。若该值大于零，且操作运行时间超过该时间，lockAsync将返回被拒绝的Promise。默认为 0。 |
AsyncLockState
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
用于存储异步锁实例上当前执行的所有锁操作的信息的类。
元服务API：从API version 12 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
属性
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| held | AsyncLockInfo[] | 否 | 否 | 持有的锁信息。 |
| pending | AsyncLockInfo[] | 否 | 否 | 等待中的锁信息。 |
AsyncLockInfo
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
关于锁的信息。
元服务API：从API version 12 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
属性
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| name | string | 否 | 否 | 锁的名称。 |
| mode | AsyncLockMode | 否 | 否 | 锁的模式。 |
| contextId | number | 否 | 否 | AsyncLockMode调用者的执行上下文标识符。 |
AbortSignal
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
用于终止异步操作的对象。该类的实例必须在其创建的同一线程中访问。从其他线程访问此类的字段会导致未定义的行为。
元服务API：从API version 12 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
属性
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| aborted | boolean | 否 | 否 | 是否终止异步操作。为true时表示终止异步操作，为false时表示异步操作未被终止。 |
| reason | T | 否 | 否 | 终止的原因。此值将用于拒绝lockAsync返回的Promise。 |
ConditionVariable18+
Phone18+PC/2in118+Tablet18+TV19+Wearable18+
实现异步等待功能的类，支持异步等待通知操作。该类使用@Sendable装饰器装饰。
元服务API：从API version 18 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
constructor18+
Phone18+PC/2in118+Tablet18+TV19+Wearable18+
constructor()
默认构造函数。创建一个异步等待通知操作的对象。
元服务API：从API version 18 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
示例：
- let conditionVariable = new ArkTSUtils.locks.ConditionVariable();
request18+
Phone18+PC/2in118+Tablet18+TV19+Wearable18+
static request(name: string): ConditionVariable
使用指定的名称查找或创建（如果未找到）异步等待通知操作的对象。
元服务API：从API version 18 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
参数：
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 按指定名称查找或创建等待通知操作的对象名称，字符串无特别限制。 |
返回值：
| 类型 | 说明 |
|---|---|
| ConditionVariable | 返回查找到或创建后的异步等待通知操作的实例。 |
示例：
- let conditionVariable = ArkTSUtils.locks.ConditionVariable.request("conditionName");
wait18+
Phone18+PC/2in118+Tablet18+TV19+Wearable18+
wait(): Promise<void>
异步调用进入等待中，将在被唤醒后继续执行。使用Promise异步回调。
元服务API：从API version 18 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
返回值：
| 类型 | 说明 |
|---|---|
| Promise<void> | 无返回结果的Promise对象。 |
示例：
- const conditionVariable: ArkTSUtils.locks.ConditionVariable = new ArkTSUtils.locks.ConditionVariable();
- conditionVariable.wait().then(() => {
- console.info(`Thread being awakened, then continue...`); // 被唤醒后输出日志
- });
waitFor18+
Phone18+PC/2in118+Tablet18+TV19+Wearable18+
waitFor(timeout: number): Promise<void>
异步调用进入等待中，将在被唤醒或者等待时间结束后继续执行。使用Promise异步回调。
元服务API：从API version 18 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
参数：
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| timeout | number | 是 | 等待时间，单位为毫秒，正整数。 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise<void> | 无返回结果的Promise对象。 |
示例：
- const conditionVariable: ArkTSUtils.locks.ConditionVariable = new ArkTSUtils.locks.ConditionVariable();
- conditionVariable.waitFor(3000).then(() => {
- console.info(`Thread being awakened, then continue...`); // 被唤醒后输出日志
- });
notifyAll18+
Phone18+PC/2in118+Tablet18+TV19+Wearable18+
notifyAll(): void
通知所有等待的线程。
元服务API：从API version 18 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
示例：
- const conditionVariable: ArkTSUtils.locks.ConditionVariable = new ArkTSUtils.locks.ConditionVariable();
- conditionVariable.waitFor(3000).then(() => {
- console.info(`Thread being awakened, then continue...`); // 被唤醒后输出日志
- });
- // 通知所有等待的线程。
- conditionVariable.notifyAll();
notifyOne18+
Phone18+PC/2in118+Tablet18+TV19+Wearable18+
notifyOne(): void
通知第一个等待的线程。
元服务API：从API version 18 开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Utils.Lang
示例：
- const conditionVariable: ArkTSUtils.locks.ConditionVariable = new ArkTSUtils.locks.ConditionVariable();
- conditionVariable.waitFor(3000).then(() => {
- console.info(`Thread a being awakened, then continue...`); // 被唤醒后输出日志
- });
- // 通知第一个等待的线程。
- conditionVariable.notifyOne();
在 开发与测试 开放能力API 中进行搜索
请输入您想要搜索的关键词