# Lock (/zh-CN/api-reference/rtm/harmonyos/lock) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 临界资源一次只能供一个进程使用,如果不同的进程之间共享了某个临界资源,则各进程需要采取互斥的方式来防止彼此干扰。RTM 提供一整套 Lock 的方案,通过控制分布式系统的不同进程,你可以解决用户在访问共享资源时的竞争问题。 :::info[信息] 客户端 SDK 具备设置、删除、撤销锁的能力,我们建议你根据实际业务需求控制端侧对锁的操作权限。 ::: ## setLock [#setlock] ### 接口描述 [#接口描述] 你需要配置锁的名称、过期时间 TTL 等属性,然后调用 `setLock` 方法进行配置。 配置成功后,频道中的所有用户会收到 `LOCK_SET` 类型的 `lock` 事件通知,详见[事件监听](/zh-CN/api-reference/rtm/harmonyos/configuration#事件监听)。 ### 接口方法 [#接口方法] 你可以通过以下方式调用 `setLock` 方法: ```typescript async setLock( channelName: string, channelType: RtmChannelType, lockName: string, options?: SetLockOptions ): Promise ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | string | 必填 | - | 频道名称。 | | `channelType` | `RtmChannelType` | 必填 | - | 频道类型。详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | | `lockName` | string | 必填 | - | 锁的名称。 | | `options` | `SetLockOptions` | 选填 | `{}` | 锁的配置选项。 | `SetLockOptions` 数据类型包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | ---- | ---- | ----- | ---- | ----------- | | `ttl` | number | 选填 | `10` | 设置锁的过期时间。单位为秒,取值范围为 [10,300]。当使用这把锁的用户掉线时,如果用户在过期时间之内重新回到频道,则该用户依旧可以使用锁;否则,该用户的锁会被释放,监听了 `lock` 事件通知的用户会收到 `LOCK_RELEASED` 事件。 | ### 返回值 [#返回值] 该方法返回一个 Promise,成功时 resolve 并返回 `SetLockResponse` 对象,失败时 reject 并抛出 `RtmError` 异常。 `SetLockResponse` 数据结构如下: | 属性 | 类型 | 描述 | | --- | --- | --- | | `timestamp` | number | 操作的时间戳(保留字段,供未来使用)。 | | `channelName` | string | 频道名称。 | | `channelType` | `RtmChannelType` | 频道类型,详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | | `lockName` | string | Lock 名称。 | ### 基本用法 [#基本用法] ```typescript import { RtmClient, RtmError, RtmChannelType } from '@shengwang/rtm-full'; try { const response = await rtmClient.lock.setLock('channelName', RtmChannelType.MESSAGE, 'lockName', { ttl: 30 }); console.log('Lock set successfully'); console.log('Lock name:', response.lockName); console.log('Channel:', response.channelName); } catch (error) { if (error instanceof RtmError) { console.error('setLock failed:', error.errorCode, error.reason); } } ``` ## acquireLock [#acquirelock] ### 接口描述 [#接口描述-1] 成功配置 Lock 后,你可以在客户端调用 `acquireLock` 方法获取锁的使用权。 成功获取锁后,频道中的其他用户会收到 `LOCK_ACQUIRED` 类型的 `lock` 事件通知,详见[事件监听](/zh-CN/api-reference/rtm/harmonyos/configuration#事件监听)。 ### 接口方法 [#接口方法-1] 你可以通过以下方式调用 `acquireLock` 方法: ```typescript async acquireLock( channelName: string, channelType: RtmChannelType, lockName: string, options?: AcquireLockOptions ): Promise ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | string | 必填 | - | 频道名称。 | | `channelType` | `RtmChannelType` | 必填 | - | 频道类型。详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | | `lockName` | string | 必填 | - | 锁的名称。 | | `options` | `AcquireLockOptions` | 选填 | `{}` | 获取锁的配置选项。 | `AcquireLockOptions` 数据类型包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | ---- | ---- | ----- | ---- | ----------- | | `retry` | boolean | 选填 | `false` | 设置在获取锁失败后是否继续尝试,直到成功获取或退出频道为止。 | ### 返回值 [#返回值-1] 该方法返回一个 Promise,成功时 resolve 并返回 `AcquireLockResponse` 对象,失败时 reject 并抛出 `RtmError` 异常。 `AcquireLockResponse` 数据结构如下: | 属性 | 类型 | 描述 | | --- | --- | --- | | `timestamp` | number | 操作的时间戳(保留字段,供未来使用)。 | | `channelName` | string | 频道名称。 | | `channelType` | `RtmChannelType` | 频道类型,详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | | `lockName` | string | Lock 名称。 | | `errorDetails` | string | 错误详情。 | ### 基本用法 [#基本用法-1] ```typescript import { RtmClient, RtmError, RtmChannelType } from '@shengwang/rtm-full'; try { const response = await rtmClient.lock.acquireLock('channelName', RtmChannelType.MESSAGE, 'lockName', { retry: false }); console.log('Lock acquired successfully'); console.log('Lock name:', response.lockName); console.log('Channel:', response.channelName); } catch (error) { if (error instanceof RtmError) { console.error('acquireLock failed:', error.errorCode, error.reason); } } ``` ## releaseLock [#releaselock] ### 接口描述 [#接口描述-2] 当用户不再需要持有某把锁时,用户可以在客户端调用 `releaseLock` 方法主动释放锁。 成功释放后,频道中的其他用户会收到 `LOCK_RELEASED` 类型的 `lock` 事件,详见[事件监听](/zh-CN/api-reference/rtm/harmonyos/configuration#事件监听)。 此时,如果其他用户想要获取该锁,可以在客户端调用 `acquireLock` 方法参与竞争。新参与获取锁的用户和之前设置 `retry` 属性自动尝试获取锁的用户的竞争优先级相同。 ### 接口方法 [#接口方法-2] 你可以通过以下方式调用 `releaseLock` 方法: ```typescript async releaseLock( channelName: string, channelType: RtmChannelType, lockName: string ): Promise ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | string | 必填 | - | 频道名称。 | | `channelType` | `RtmChannelType` | 必填 | - | 频道类型。详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | | `lockName` | string | 必填 | - | 锁的名称。 | ### 返回值 [#返回值-2] 该方法返回一个 Promise,成功时 resolve 并返回 `ReleaseLockResponse` 对象,失败时 reject 并抛出 `RtmError` 异常。 `ReleaseLockResponse` 数据结构如下: | 属性 | 类型 | 描述 | | --- | --- | --- | | `timestamp` | number | 操作的时间戳(保留字段,供未来使用)。 | | `channelName` | string | 频道名称。 | | `channelType` | `RtmChannelType` | 频道类型,详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | | `lockName` | string | Lock 名称。 | ### 基本用法 [#基本用法-2] ```typescript import { RtmClient, RtmError, RtmChannelType } from '@shengwang/rtm-full'; try { const response = await rtmClient.lock.releaseLock('channelName', RtmChannelType.MESSAGE, 'lockName'); console.log('Lock released successfully'); console.log('Lock name:', response.lockName); console.log('Channel:', response.channelName); } catch (error) { if (error instanceof RtmError) { console.error('releaseLock failed:', error.errorCode, error.reason); } } ``` ## revokeLock [#revokelock] ### 接口描述 [#接口描述-3] 当锁被占用时,为保证你的业务不受影响,你可能需要收回该锁,并让其他用户有机会获取该锁。调用 `revokeLock` 收回被占用的锁。 成功收回后,频道中的所有用户会收到 `LOCK_RELEASED` 类型的 `lock` 事件,详见[事件监听](/zh-CN/api-reference/rtm/harmonyos/configuration#事件监听)。 此时,如果其他用户想要获取该锁,可以在客户端调用 `acquireLock` 方法参与竞争。新参与获取锁的用户和之前设置 `retry` 属性自动尝试获取锁的用户的竞争优先级相同。 ### 接口方法 [#接口方法-3] 你可以通过以下方式调用 `revokeLock` 方法: ```typescript async revokeLock( channelName: string, channelType: RtmChannelType, lockName: string, owner: string ): Promise ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | string | 必填 | - | 频道名称。 | | `channelType` | `RtmChannelType` | 必填 | - | 频道类型。详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | | `lockName` | string | 必填 | - | 锁的名称。 | | `owner` | string | 必填 | - | 拥有锁的用户 ID。 | ### 返回值 [#返回值-3] 该方法返回一个 Promise,成功时 resolve 并返回 `RevokeLockResponse` 对象,失败时 reject 并抛出 `RtmError` 异常。 `RevokeLockResponse` 数据结构如下: | 属性 | 类型 | 描述 | | --- | --- | --- | | `timestamp` | number | 操作的时间戳(保留字段,供未来使用)。 | | `channelName` | string | 频道名称。 | | `channelType` | `RtmChannelType` | 频道类型,详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | | `lockName` | string | Lock 名称。 | ### 基本用法 [#基本用法-3] ```typescript import { RtmClient, RtmError, RtmChannelType } from '@shengwang/rtm-full'; try { const response = await rtmClient.lock.revokeLock('channelName', RtmChannelType.MESSAGE, 'lockName', 'tony'); console.log('Lock revoked successfully'); console.log('Lock name:', response.lockName); console.log('Channel:', response.channelName); } catch (error) { if (error instanceof RtmError) { console.error('revokeLock failed:', error.errorCode, error.reason); } } ``` ## getLocks [#getlocks] ### 接口描述 [#接口描述-4] 如果你需要查询频道中锁的数量、名称、使用者、过期时间等信息,在客户端调用 `getLocks` 方法。 ### 接口方法 [#接口方法-4] 你可以通过以下方式调用 `getLocks` 方法: ```typescript async getLocks( channelName: string, channelType: RtmChannelType ): Promise ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | string | 必填 | - | 频道名称。 | | `channelType` | `RtmChannelType` | 必填 | - | 频道类型。详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | ### 返回值 [#返回值-4] 该方法返回一个 Promise,成功时 resolve 并返回 `GetLocksResponse` 对象,失败时 reject 并抛出 `RtmError` 异常。 `GetLocksResponse` 数据结构如下: | 属性 | 类型 | 描述 | | --- | --- | --- | | `timestamp` | number | 操作的时间戳(保留字段,供未来使用)。 | | `channelName` | string | 频道名称。 | | `channelType` | `RtmChannelType` | 频道类型,详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | | `lockDetails` | `LockDetail[]` | Lock 详情数组。 | `LockDetail` 数据类型包含以下属性: | 属性 | 类型 | 描述 | | --- | --- | --- | | `lockName` | string | Lock 的名称。 | | `owner` | string | 拥有锁的用户 ID。 | | `ttl` | number | 锁的过期时间。当使用这把锁的用户掉线时,如果用户在过期时间之内重新回到频道,则该用户依旧可以使用锁;否则,该用户的锁会被释放,监听了 `lock` 事件通知的用户会收到 `LOCK_RELEASED` 事件。 | ### 基本用法 [#基本用法-4] ```typescript import { RtmClient, RtmError, RtmChannelType } from '@shengwang/rtm-full'; try { const response = await rtmClient.lock.getLocks('channelName', RtmChannelType.MESSAGE); console.log('Locks retrieved successfully'); console.log('Total locks:', response.lockDetails.length); console.log('Channel:', response.channelName); response.lockDetails.forEach((lock) => { console.log(`Lock: ${lock.lockName}`); console.log(` Owner: ${lock.owner || 'none'}`); console.log(` TTL: ${lock.ttl}s`); }); } catch (error) { if (error instanceof RtmError) { console.error('getLocks failed:', error.errorCode, error.reason); } } ``` ## removeLock [#removelock] ### 接口描述 [#接口描述-5] 如果你不再需要频道中的某把锁,你可以调用 `removeLock` 方法删除该锁。 成功删除锁后,频道中的所有用户会收到 `LOCK_REMOVED` 类型的 `lock` 事件通知,详见[事件监听](/zh-CN/api-reference/rtm/harmonyos/configuration#事件监听)。 ### 接口方法 [#接口方法-5] 你可以通过以下方式调用 `removeLock` 方法: ```typescript async removeLock( channelName: string, channelType: RtmChannelType, lockName: string ): Promise ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | string | 必填 | - | 频道名称。 | | `channelType` | `RtmChannelType` | 必填 | - | 频道类型。详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | | `lockName` | string | 必填 | - | 锁的名称。 | ### 返回值 [#返回值-5] 该方法返回一个 Promise,成功时 resolve 并返回 `RemoveLockResponse` 对象,失败时 reject 并抛出 `RtmError` 异常。 `RemoveLockResponse` 数据结构如下: | 属性 | 类型 | 描述 | | --- | --- | --- | | `timestamp` | number | 操作的时间戳(保留字段,供未来使用)。 | | `channelName` | string | 频道名称。 | | `channelType` | `RtmChannelType` | 频道类型,详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | | `lockName` | string | Lock 名称。 | ### 基本用法 [#基本用法-5] ```typescript import { RtmClient, RtmError, RtmChannelType } from '@shengwang/rtm-full'; try { const response = await rtmClient.lock.removeLock('channelName', RtmChannelType.MESSAGE, 'lockName'); console.log('Lock removed successfully'); console.log('Lock name:', response.lockName); console.log('Channel:', response.channelName); } catch (error) { if (error instanceof RtmError) { console.error('removeLock failed:', error.errorCode, error.reason); } } ```