coroutine

执行契约

• 协程固定归属于创建它的原生线程，Resume、活跃对象的销毁和调度操作只能在该线程执行。
• Windows 使用 CreateFiberEx 的可增长栈，仅保留 StackSize 指定的虚拟地址空间，并从较小提交量开始按需增长。
• POSIX 原生后端使用匿名映射和不可访问保护页；可写映射由操作系统按首次访问提交物理页面。
• 每个协程拥有独立的临时内存 arena、结构化错误上下文和取消令牌。
• xrtCoCancelToken 返回增加引用后的取消令牌，调用方使用完毕后必须调用 xrtCancelDestroy。
• 取消是协作式的。xrtCoYield 在恢复后返回 XWAIT_CANCELLED，未启动的已取消协程不会执行用户过程。
• 取消请求与终态正交：处理请求后正常返回仍是 XCORO_TERM_RETURNED；调用 xrtCoConfirmCancel 后返回才是 XCORO_TERM_CANCELLED。
• 用户过程正常返回时若仍留有未处理错误，终态为 XCORO_TERM_ERROR；显式确认取消优先于残留错误。

生命周期

xrtCoCreate 创建 XCORO_READY 对象。xrtCoResume 运行到下一次 xrtCoYield 或过程返回。只有未启动的 READY 对象和 DONE 对象可以由 xrtCoDestroy 销毁；拒绝销毁活跃栈可避免跳过清理过程或留下悬空上下文。

外部创建的线程在最后一个协程结束后可调用 xrtCoThreadDetach 释放惰性线程运行时。xrtThreadCreate 创建的线程会在退出时自动执行该步骤；仍有挂起协程时 detach 会失败。

xrtCoStopping 用于查询当前协程是否收到取消请求。等待函数返回 XWAIT_CANCELLED 后，用户代码可以清理并正常返回结果；确实要把本次执行记为取消时调用 xrtCoConfirmCancel。没有取消请求、普通线程路径或清理栈中调用确认函数都会失败并设置 XERR_STATE。

平台后端

所有原生后端保存 ABI 规定的整数和浮点非易失寄存器。当前发布构建必须在对应目标上执行上下文、深栈和浮点寄存器测试；仅在其他平台编译成功不能替代运行验证。

POSIX 手工栈切换在 AddressSanitizer 构建中使用官方 fiber switch 接口登记栈范围和 fake stack，协程永久结束时主动释放其 fake stack；MemorySanitizer 构建使用对应的 fiber switch 接口登记新旧栈边界；ThreadSanitizer 构建为每个协程维护独立 fiber 身份，避免把不同协程的访问历史混为同一执行上下文。Sanitizer 发布门禁必须使用包含对应运行时的插桩工具链实际执行，只有编译或链接结果不能替代运行验证。Linux x86-64 在启用 CET 时同时支持 IBT 和 shadow stack：内部恢复点包含 ENDBR64，每个协程按需映射独立 shadow stack 并随协程销毁。其他 x86-64 系统若要求 SHSTK，编译阶段会明确拒绝，不能静默生成不完整上下文。

清理栈

清理栈提供两层 API：

• xrtCoDefer 是常用路径，由协程分配并管理节点，过程返回后仍可可靠执行。
• xrtCoCleanupPush 是无分配路径，节点必须先使用 XRT_CO_CLEANUP_INIT 或全零初始化，且存储期必须覆盖协程终态；不能把未弹出的节点放在协程过程的自动局部变量中。

xrtCoCleanupPop 可以弹出任一种节点，并可选择立即执行。所有仍在栈上的清理过程按后进先出顺序执行，清理过程中禁止让出协程。

调度器

XRT_FEATURE_COROUTINE_SCHEDULER 在核心之上增加单线程调度器。调度器、执行队列、timer heap 和 join 链只由所属线程修改；跨线程入口只把工作放入互斥保护的 FIFO 队列，再由所属线程修改执行结构。

• xrtCoSpawn 返回保留句柄。协程完成后仍可读取 Term、Result 和 Error，最后由 xrtCoDestroy 或调度器销毁。
• xrtCoGo 创建分离协程，完成后自动回收，适合不需要结果的后台过程。
• xrtCoSchedPost 从任意线程投递借用数据的短过程；xrtCoSchedPostOwned 在受理后接管数据，并在过程返回后恰好析构一次。失败时 Owned 数据仍归调用方。
• xrtCoPark、ParkFor、ParkUntil 区分 OK、TIMEOUT 和 CANCELLED；提前 wake 会保留到下一次 park，不会丢失。
• xrtCoSleep 和 SleepUntil 自然到期返回 OK，取消返回 CANCELLED。
• xrtCoJoin 只接受同一调度器的保留句柄，支持多个等待者、deadline、取消和依赖环检测。
• xrtCoSchedClose 停止接收新协程和新投递，并协作取消全部活跃协程；关闭前已经受理的投递仍按 FIFO 顺序排空。

投递过程运行在所属线程的普通调用栈中，不在协程内，不能调用 yield、park 或 await；它应只做创建协程、完成 Promise、更新短状态等不可阻塞操作。每次 xrtCoSchedStep 或 Poll 至多执行一个通用投递并恢复一个协程。没有活跃协程和待执行投递时返回 XWAIT_CLOSED，用户截止时间到达但仍有挂起协程时返回 XWAIT_TIMEOUT。

xrtCoSchedRun 会排空调用时已经受理的投递和由它们创建的协程。它不是永久驻留的事件循环：当活跃协程和投递同时归零时返回。销毁前必须停止其他线程访问；有尚未执行的投递时，xrtCoSchedDestroy 返回 XERR_STATE，不会静默丢弃回调或 Owned 数据。

xrtCoSchedCreate() 默认限制 1024 个尚未执行的用户投递（XRT_CO_SCHED_POST_LIMIT_DEFAULT）。xrtCoSchedCreateLimit(n) 可在创建时调整；0 使用默认值，SIZE_MAX 显式取消实际限额。队满立即返回 false / XERR_AGAIN，不接管 Owned 数据。过程从队列取出时释放名额，因此过程内部也可以继续投递。内部协程唤醒使用独立的无分配链，不受用户队列预算影响；已有批量生产者若一次提交超过 1024 项，需要显式预算或处理背压。

xrtCoWake 线程安全，但句柄销毁不是并发操作。调用方必须保证 wake 返回前目标及所属调度器仍然有效；需要跨线程管理寿命时，应由更高层 Future/Task 持有引用，而不是裸传 xcoro*。

协程事件

XRT_FEATURE_COROUTINE_EVENT 提供调度器原生的 xcoevent，用于不阻塞所属线程地等待一次跨线程通知。它依赖 coroutine_scheduler，但不依赖线程事件的内核等待对象。

• xrtCoEventInit / Unit 使用调用方固定存储；Create / Destroy 是对应的堆对象易用层。
• 自动复位事件每次 Set 按 FIFO 唤醒一个等待者；没有等待者时保存一个信号。
• 手动复位事件每次 Set 唤醒全部等待者并保持信号态，直到 Reset。
• Await、TryAwait、AwaitFor 和 AwaitUntil 分别返回 OK、TIMEOUT、CANCELLED 或 ERROR。
• 每次 Await 使用协程栈上的等待节点，不产生堆分配；跨线程 Set 通过调度器等待代际投递，不会丢失注册期间的信号。
• Unit / Destroy 与其他操作不能并发。只要仍有 Await 尚未返回，即使它已经获得信号，释放也会以 XERR_STATE 失败并保持对象有效。

通用 xrtCoWake 只能促使 Await 重新检查条件，不能伪造事件信号。终结过程中的 Await 在读取或消费事件信号前失败。

公共类型与常量