裁剪与依赖

启用 XRT_FEATURE_SPIN，模块依赖 atomic。未启用时不声明类型和函数，也不编译实现。

生命周期

栈上对象使用 xrtSpinInit() 和 xrtSpinUnit()，静态对象使用 XRT_SPIN_INIT，动态对象使用 xrtSpinCreate() 和 xrtSpinDestroy()。释放仍被持有的锁会失败并设置 XERR_STATE。

进入与退出

xrtSpinLock() 等待直到获得锁。xrtSpinTryLock() 只尝试一次，锁繁忙时返回 false 且不设置错误。xrtSpinUnlock() 使用 Release 顺序发布临界区内的写入。

锁不记录线程所有者，调用方必须保证只有持有者执行解锁；同一执行流重复进入会永久等待。协程、任务或网络 Worker 不应在持锁期间执行阻塞、等待或用户回调。

完整示例位于 examples/concurrency/spin，竞争回归位于 tests/concurrency/test_spin_threads.c。

xspinlock类型

短临界区自旋锁不记录所有者，也不支持递归进入。

字段类型语义
Statexatomic32状态
Magicuint32魔数
typedef struct xspinlock { xatomic32 State; uint32 Magic; } xspinlock;

xrtSpinInit函数

初始化调用方提供的自旋锁存储。

bool xrtSpinInit(xspinlock* pSpin)

参数

参数方向约束说明
pSpin输出非空接收自旋锁
返回值
返回含义失败时状态
true已初始化—
false参数非法XERR_ARGUMENT
错误
  • XERR_ARGUMENT — 指针为空或参数非法

范例已编译验证

spin · 初始化

	if ( !xrtSpinInit(&Spin) ) {

xrtSpinUnit函数

释放自旋锁状态；锁仍被持有时失败。

bool xrtSpinUnit(xspinlock* pSpin)

参数

参数方向约束说明
pSpin输入非空、未持有目标自旋锁
返回值
返回含义失败时状态
true已释放—
false锁仍被持有XERR_STATE
错误
  • XERR_ARGUMENT — 指针为空或参数非法
  • XERR_STATE — 锁仍被持有、未初始化或状态非法

范例已编译验证

spin · 释放状态

	if ( !xrtSpinUnlock(&Spin) || !xrtSpinUnit(&Spin) ) {

xrtSpinCreate函数

创建一个动态分配的自旋锁。

xspinlock* xrtSpinCreate()

参数

参数方向约束说明
无参数———
返回值
返回含义失败时状态
非空自旋锁—
NULL分配失败XERR_MEMORY
错误
  • XERR_MEMORY — 分配失败

范例已编译验证

spin · 堆创建

		xspinlock* pHeap = xrtSpinCreate();

xrtSpinDestroy函数

释放动态自旋锁；空指针视为空操作。

bool xrtSpinDestroy(xspinlock* pSpin)

参数

参数方向约束说明
pSpin输入允许空空 = 空操作
返回值
返回含义失败时状态
true已释放—
false锁仍被持有XERR_STATE
错误
  • XERR_STATE — 锁仍被持有时空指针之外路径失败

范例已编译验证

spin · 销毁

			!xrtSpinDestroy(pHeap) ) {

xrtSpinLock函数

自适应等待并进入短临界区。

bool xrtSpinLock(xspinlock* pSpin)

参数

参数方向约束说明
pSpin输入非空、已初始化目标自旋锁
返回值
返回含义失败时状态
true已进入临界区—
false参数或状态非法XERR_ARGUMENT / XERR_STATE
错误
  • XERR_ARGUMENT — 指针为空或参数非法
  • XERR_STATE — 锁仍被持有、未初始化或状态非法

范例已编译验证

spin · 加锁

	if ( !xrtSpinLock(&Spin) ) {

xrtSpinTryLock函数

尝试进入短临界区；锁繁忙时不设置错误。

bool xrtSpinTryLock(xspinlock* pSpin)

参数

参数方向约束说明
pSpin输入非空、已初始化目标自旋锁
返回值
返回含义失败时状态
true已进入临界区—
false锁繁忙或参数非法忙碌不设错
错误
  • 锁繁忙返回 false 且不设置错误；参数或状态非法 XERR_ARGUMENT / XERR_STATE

范例已编译验证

spin · 尝试加锁

			xrtSpinTryLock(pHeap) ||  /* 已持有：Try 必失败 */

xrtSpinUnlock函数

离开短临界区。

bool xrtSpinUnlock(xspinlock* pSpin)

参数

参数方向约束说明
pSpin输入非空、已持有目标自旋锁
返回值
返回含义失败时状态
true已离开临界区—
false未持有或参数非法XERR_STATE / XERR_ARGUMENT
错误
  • XERR_ARGUMENT — 指针为空或参数非法
  • XERR_STATE — 锁仍被持有、未初始化或状态非法

范例已编译验证

spin · 解锁

	if ( !xrtSpinUnlock(&Spin) || !xrtSpinUnit(&Spin) ) {

常量索引常量

以下常量在本页所属头文件中定义，语义见公共头注释。

常量说明
XRT_SPIN_INIT见头文件注释
XRT_SPIN_MAGIC见头文件注释