需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

Lock

  • C++

更新时间不可用

临界资源一次只能供一个进程使用，如果不同的进程之间共享了某个临界资源，则各进程需要采取互斥的方式来防止彼此干扰。RTM 提供一整套 Lock 的方案，通过控制分布式系统的不同进程，你可以解决用户在访问共享资源时的竞争问题。

信息

客户端 SDK 具备设置、删除、撤销锁的能力，我们建议你根据实际业务需求控制端侧对锁的操作权限。

setLock

接口描述

你需要配置锁的名称、过期时间 TTL 等属性，然后调用 setLock 方法进行配置。

配置成功后，频道中的所有用户会收到 RTM_LOCK_EVENT_TYPE_LOCK_SET 类型的 onLockEvent 事件通知，详见事件监听。

接口方法

你可以通过以下方式调用 setLock 方法：

C++
virtual void setLock(const char* channelName, RTM_CHANNEL_TYPE channelType, const char* lockName, uint32_t ttl, uint64_t& requestId) = 0;
参数类型是否必填默认值描述
channelNameconst char*必填-频道名称。
channelTypeRTM_CHANNEL_TYPE必填-频道类型。详见 RTM_CHANNEL_TYPE。
lockNameconst char*必填-锁的名称。
ttluint32_t必填-设置锁的过期时间。单位为秒，取值范围为 [10,300]。当使用这把锁的用户掉线时，如果用户在过期时间之内重新回到频道，则该用户依旧可以使用锁；否则，该用户的锁会被释放，监听了 onLockEvent 事件通知的用户会收到 RTM_LOCK_EVENT_TYPE_LOCK_RELEASED 事件。
requestIduint64_t&必填-（输出参数）请求标识符，后续用于识别和处理相应的请求。
表格内容超出当前宽度，可横向滚动查看更多列。

异步回调

调用该方法后，SDK 会触发 onSetLockResult 回调并通过以下参数返回 API 调用结果：

参数类型描述
requestIdconst uint64_t请求标识符。
channelNameconst char*频道名称。
channelTypeRTM_CHANNEL_TYPE频道类型，详见 RTM_CHANNEL_TYPE。
lockNameconst char*Lock 名称。
errorCodeRTM_ERROR_CODE错误码，详见错误排查。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

C++
// 方法调用
uint64_t requestId;
rtm_client->getLock()->setLock("channelName", RTM_CHANNEL_TYPE_MESSAGE, "lockName", 30, requestId);

acquireLock

接口描述

成功配置 Lock 后，你可以在客户端调用 acquireLock 方法获取锁的使用权。

成功获取锁后，频道中的其他用户会收到 RTM_LOCK_EVENT_TYPE_LOCK_ACQUIRED 类型的 onLockEvent 事件通知，详见事件监听。

接口方法

你可以通过以下方式调用 acquireLock 方法：

C++
virtual void acquireLock(const char* channelName, RTM_CHANNEL_TYPE channelType, const char* lockName, bool retry, uint64_t& requestId) = 0;
参数类型是否必填默认值描述
channelNameconst char*必填-频道名称。
channelTypeRTM_CHANNEL_TYPE必填-频道类型。详见 RTM_CHANNEL_TYPE。
lockNameconst char*必填-锁的名称。
retrybool必填-设置在获取锁失败后是否继续尝试，直到成功获取或退出频道为止。
requestIduint64_t&必填-（输出参数）请求标识符，后续用于识别和处理相应的请求。
表格内容超出当前宽度，可横向滚动查看更多列。

异步回调

调用该方法后，SDK 会触发 onAcquireLockResult 回调并通过以下参数返回 API 调用结果：

参数类型描述
requestIdconst uint64_t请求标识符。
channelNameconst char*频道名称。
channelTypeRTM_CHANNEL_TYPE频道类型，详见 RTM_CHANNEL_TYPE。
lockNameconst char*Lock 名称。
errorCodeRTM_ERROR_CODE错误码，详见错误排查。
errorDetailsconst char*错误详情。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

C++
// 方法调用
uint64_t requestId;
rtmClient->getLock()->acquireLock("channelName", RTM_CHANNEL_TYPE_MESSAGE, "lockName", false, requestId);

releaseLock

接口描述

当用户不再需要持有某把锁时，用户可以在客户端调用 releaseLock 方法主动释放锁。

成功释放后，频道中的其他用户会收到 RTM_LOCK_EVENT_TYPE_LOCK_RELEASED 类型的 onLockEvent 事件，详见事件监听。

此时，如果其他用户想要获取该锁，可以在客户端调用 acquireLock 方法参与竞争。新参与获取锁的用户和之前设置 retry 属性自动尝试获取锁的用户的竞争优先级相同。

接口方法

你可以通过以下方式调用 releaseLock 方法：

C++
virtual void releaseLock(const char* channelName, RTM_CHANNEL_TYPE channelType, const char* lockName, uint64_t& requestId) = 0;
参数类型是否必填默认值描述
channelNameconst char*必填-频道名称。
channelTypeRTM_CHANNEL_TYPE必填-频道类型。详见 RTM_CHANNEL_TYPE。
lockNameconst char*必填-锁的名称。
requestIduint64_t&必填-（输出参数）请求标识符，后续用于识别和处理相应的请求。
表格内容超出当前宽度，可横向滚动查看更多列。

异步回调

调用该方法后，SDK 会触发 onReleaseLockResult 回调并通过以下参数返回 API 调用结果：

参数类型描述
requestIdconst uint64_t请求标识符。
channelNameconst char*频道名称。
channelTypeRTM_CHANNEL_TYPE频道类型，详见 RTM_CHANNEL_TYPE。
lockNameconst char*Lock 名称。
errorCodeRTM_ERROR_CODE错误码，详见错误排查。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

C++
// 方法调用
uint64_t requestId;
rtmClient->getLock()->releaseLock("channelName", RTM_CHANNEL_TYPE_MESSAGE, "lockName", requestId);

revokeLock

接口描述

当锁被占用时，为保证你的业务不受影响，你可能需要收回该锁，并让其他用户有机会获取该锁。调用 revokeLock 收回被占用的锁。

成功收回后，频道中的所有用户会收到 RTM_LOCK_EVENT_TYPE_LOCK_RELEASED 类型的 onLockEvent 事件，详见事件监听。

此时，如果其他用户想要获取该锁，可以在客户端调用 acquireLock 方法参与竞争。新参与获取锁的用户和之前设置 retry 属性自动尝试获取锁的用户的竞争优先级相同。

接口方法

你可以通过以下方式调用 revokeLock 方法：

C++
virtual void revokeLock(const char* channelName, RTM_CHANNEL_TYPE channelType, const char* lockName, const char* owner, uint64_t& requestId) = 0;
参数类型是否必填默认值描述
channelNameconst char*必填-频道名称。
channelTypeRTM_CHANNEL_TYPE必填-频道类型。详见 RTM_CHANNEL_TYPE。
lockNameconst char*必填-锁的名称。
ownerconst char*必填-拥有锁的用户 ID。
requestIduint64_t&必填-（输出参数）请求标识符，后续用于识别和处理相应的请求。
表格内容超出当前宽度，可横向滚动查看更多列。

异步回调

调用该方法后，SDK 会触发 onRevokeLockResult 回调并通过以下参数返回 API 调用结果：

参数类型描述
requestIdconst uint64_t请求标识符。
channelNameconst char*频道名称。
channelTypeRTM_CHANNEL_TYPE频道类型，详见 RTM_CHANNEL_TYPE。
lockNameconst char*Lock 名称。
errorCodeRTM_ERROR_CODE错误码，详见错误排查。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

C++
// 方法调用
uint64_t requestId;
rtmClient->getLock()->revokeLock("channelName", RTM_CHANNEL_TYPE_MESSAGE, "lockName", "tony", requestId);

getLocks

接口描述

如果你需要查询频道中锁的数量、名称、使用者、过期时间等信息，在客户端调用 getLocks 方法。

接口方法

你可以通过以下方式调用 getLocks 方法：

C++
virtual void getLocks(const char* channelName, RTM_CHANNEL_TYPE channelType, uint64_t& requestId) = 0;
参数类型是否必填默认值描述
channelNameconst char*必填-频道名称。
channelTypeRTM_CHANNEL_TYPE必填-频道类型。详见 RTM_CHANNEL_TYPE。
requestIduint64_t&必填-（输出参数）请求标识符，后续用于识别和处理相应的请求。
表格内容超出当前宽度，可横向滚动查看更多列。

异步回调

调用该方法后，SDK 会触发 onGetLocksResult 回调并通过以下参数返回 API 调用结果：

参数类型描述
requestIdconst uint64_t请求标识符。
channelNameconst char*频道名称。
channelTypeRTM_CHANNEL_TYPE频道类型，详见 RTM_CHANNEL_TYPE。
lockDetailListconst LockDetail*Lock 详情。
countconst size_tLock 数量。
errorCodeRTM_ERROR_CODE错误码，详见错误排查。
表格内容超出当前宽度，可横向滚动查看更多列。

LockDetail 数据类型包含以下属性：

属性类型描述
lockNameconst char*Lock 的名称。
ownerconst char*拥有锁的用户 ID。
ttluint32_t锁的过期时间。当使用这把锁的用户掉线时，如果用户在过期时间之内重新回到频道，则该用户依旧可以使用锁；否则，该用户的锁会被释放，监听了 onLockEvent 事件通知的用户会收到 RTM_LOCK_EVENT_TYPE_LOCK_RELEASED 事件。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

C++
// 方法调用
uint64_t requestId;
rtmClient->getLock()->getLocks("channelName", RTM_CHANNEL_TYPE_MESSAGE, requestId);

removeLock

接口描述

如果你不再需要频道中的某把锁，你可以调用 removeLock 方法删除该锁。

成功删除锁后，频道中的所有用户会收到 RTM_LOCK_EVENT_TYPE_LOCK_REMOVED 类型的 onLockEvent 事件通知，详见事件监听。

接口方法

你可以通过以下方式调用 removeLock 方法：

C++
virtual void removeLock(const char* channelName, RTM_CHANNEL_TYPE channelType, const char* lockName, uint64_t& requestId) = 0;
参数类型是否必填默认值描述
channelNameconst char*必填-频道名称。
channelTypeRTM_CHANNEL_TYPE必填-频道类型。详见 RTM_CHANNEL_TYPE。
lockNameconst char*必填-锁的名称。
requestIduint64_t&必填-（输出参数）请求标识符，后续用于识别和处理相应的请求。
表格内容超出当前宽度，可横向滚动查看更多列。

异步回调

调用该方法后，SDK 会触发 onRemoveLockResult 回调并通过以下参数返回 API 调用结果：

参数类型描述
requestIdconst uint64_t请求标识符。
channelNameconst char*频道名称。
channelTypeRTM_CHANNEL_TYPE频道类型，详见 RTM_CHANNEL_TYPE。
lockNameconst char*Lock 名称。
errorCodeRTM_ERROR_CODE错误码，详见错误排查。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

C++
// 方法调用
uint64_t requestId;
rtmClient->getLock()->removeLock("channelName", RTM_CHANNEL_TYPE_MESSAGE, "lockName", requestId);

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利