模块契约原生异步文件 I/O

错误

失败经 xrtGetError() 报告：

域/种类触发场景
XERR_ARGUMENT / XERR_STATE / XERR_RANGE参数、Worker 归属与偏移范围
XERR_UNSUPPORTEDWorker 端口后端无原生文件 I/O 能力
xrt.net / XNET_ERROR_PORT_SUBMIT提交失败（RANGE/UNSUPPORTED 等 kind）
xrt.file 域错误打开失败（同 xrtFileOpen）

生命周期

  • 使用 xrtNetFileOpen 打开文件；函数自动附加 XFILE_ASYNC。
  • 同一文件在首次提交后固定由同一个 Worker 使用。
  • 文件、缓冲和 xnetcompletion 必须保持到操作产生唯一终态事件。
  • 全部操作终结后使用 xrtClose 关闭文件。
  • xrtNetFileCancel 只请求取消；资源仍在原操作终态回调后释放。

Windows 使用 IOCP ReadFile/WriteFile，Linux 使用 io_uring READV/WRITEV。 其他后端通过能力位明确报告不支持，不会退化为阻塞 Worker。

xrtNetFileOpen函数

打开可提交到完成端口的文件；自动附加 XFILE_ASYNC，不改变调用方选项对象。

xfile xrtNetFileOpen(cstr sPath, const xfileoptions* pOptions)

参数

参数方向约束说明
sPath输入非空文件路径
pOptions输入允许空空 = xrtFileOptionsInit 默认值
返回值
返回含义失败时状态
非空异步文件句柄—
空打开失败xrt.file 域错误
错误
  • xrt.file 域错误 — 路径非法、权限不足或共享冲突（同 xrtFileOpen）

范例已编译验证

file_tour · 打开

		File = xrtNetFileOpen(sFile, &Options);

xrtNetFileRead函数

从绝对偏移读取到调用方缓冲，返回非零操作标识；只能在所属 Worker 执行。

uint64 xrtNetFileRead(xnetworker* pWorker, xfile File, uint64 iOffset, void* pData, size_t iSize, xnetcompletion* pCompletion)

参数

参数方向约束说明
pWorker输入非空、当前线程目标 Worker
File输入xrtNetFileOpen 产物异步文件句柄
iOffset输入—绝对读取偏移
pData输入/输出非空调用方缓冲，保持到终态
iSize输入> 0读取字节数
pCompletion输入非空且 Proc 非空终态回调，保持到唯一终态
返回值
返回含义失败时状态
非零操作标识，与终态事件 Id 对应—
0提交失败见错误
错误
  • XERR_ARGUMENT — Worker、文件、Completion（含 Proc）、缓冲为空或长度为 0
  • XERR_STATE — 不在所属 Worker 线程，或文件未附加异步/缺少对应访问标志
  • xrt.net / XNET_ERROR_PORT_SUBMIT（XERR_RANGE） — 偏移 + 长度超出完成事件可表达范围
  • XERR_UNSUPPORTED — Worker 端口后端无原生文件 I/O 能力（如 SELECT 后端）

范例已编译验证

file_tour · 定位读取

	pTask->iId = xrtNetFileRead(pTask->pWorker, pTask->File,
		pTask->iOffset, (void*)pTask->pData, pTask->iSize,
		&pTask->pIo->Completion);

xrtNetFileWrite函数

把调用方缓冲写入绝对偏移，返回非零操作标识；热路径不复制载荷。

uint64 xrtNetFileWrite(xnetworker* pWorker, xfile File, uint64 iOffset, const void* pData, size_t iSize, xnetcompletion* pCompletion)

参数

参数方向约束说明
pWorker输入非空、当前线程目标 Worker
File输入含写入访问异步文件句柄
iOffset输入—绝对写入偏移
pData输入非空载荷缓冲，保持到终态
iSize输入> 0写入字节数
pCompletion输入非空且 Proc 非空终态回调，保持到唯一终态
返回值
返回含义失败时状态
非零操作标识，与终态事件 Id 对应—
0提交失败见错误
错误
  • XERR_ARGUMENT — Worker、文件、Completion（含 Proc）、缓冲为空或长度为 0
  • XERR_STATE — 不在所属 Worker 线程，或文件未附加异步/缺少对应访问标志
  • xrt.net / XNET_ERROR_PORT_SUBMIT（XERR_RANGE） — 偏移 + 长度超出完成事件可表达范围
  • XERR_UNSUPPORTED — Worker 端口后端无原生文件 I/O 能力（如 SELECT 后端）

范例已编译验证

file_tour · 定位写入

	pTask->iId = xrtNetFileWrite(pTask->pWorker, pTask->File,
		pTask->iOffset, pTask->pData, pTask->iSize,
		&pTask->pIo->Completion);

xrtNetFileCancel函数

在所属 Worker 请求取消操作；原操作仍通过 Completion 产生唯一终态。

bool xrtNetFileCancel(xnetworker* pWorker, uint64 Id)

参数

参数方向约束说明
pWorker输入非空、当前线程目标 Worker
Id输入非零要取消的操作标识
返回值
返回含义失败时状态
true取消请求已受理—
false参数非法或不在所属线程XERR_ARGUMENT / XERR_STATE
错误
  • XERR_ARGUMENT — Worker 为空或 Id 为 0
  • XERR_STATE — 不在所属 Worker 线程

范例已编译验证

file_tour · 请求取消

				if ( !xrtNetFileCancel(Task.pWorker,
						iCancelId) ||
					!exampleSpin(&CancelIo,

							3000) ) {