fsys.atomicFile 库模块帮助文档

原子文件替换

fsys.atomicFile 成员列表 #

本地固定磁盘 NTFS 的单文件原子命名替换。
不是多文件事务或掉电耐久保证；不保留旧目标 ACL/时间戳/备用流，不自动创建父目录。

fsys.atomicFile.prepare() #

返回对象:atomicPreparedObject

fsys.atomicFile.prepare(目标路径,字符串或buffer,选项表) #

在目标同目录独占创建临时文件，完整写入，默认 FlushFileBuffers。
成功返回 prepared 对象；失败返回 null,错误信息,结果表。结果含 cleanupError/pending 时必须处理清理失败。

fsys.atomicFile.write() #

返回对象:atomicFileResultObject

fsys.atomicFile.write(目标路径,字符串或buffer,选项表) #

准备并提交；失败自动清理未提交临时文件。始终返回结果表，不要直接把结果当布尔值。
选项仅 flush=true、replaceExisting=true；false 可禁用刷新或只创建不覆盖。无自动重试。

atomicFileResultObject 成员列表 #

atomicFileResultObject.bytesWritten #

成功写入调用所报告的字节总数。

atomicFileResultObject.cleanupError #

独立清理错误 {code;message;systemCode}，不意味着提交被撤销。

atomicFileResultObject.code #

主错误代码；error 为描述，systemCode 为可选 Win32 错误代码。

atomicFileResultObject.committed #

是否已完成原子重命名；一旦 true 不会因后续清理失败变回 false。

atomicFileResultObject.error #

主错误描述；准备失败或提交失败不会被后续 cleanupError 掩盖。

atomicFileResultObject.flushed #

是否成功请求过提交前 FlushFileBuffers；不是断电耐久保证。

atomicFileResultObject.handleOpen #

本对象是否仍持有句柄。

atomicFileResultObject.ok #

本次请求及必要清理是否全部完成；请同时检查 committed。

atomicFileResultObject.pending #

write/prepare 失败时仍持句柄的对象；保留并调用 close 重试清理，不要盲目重写目标。

atomicFileResultObject.pending. #

返回对象:atomicPreparedObject

atomicFileResultObject.state #

new / prepared / aborting / aborted / committed。

atomicFileResultObject.targetPath #

规范化目标绝对路径。

atomicFileResultObject.tempPath #

临时文件原绝对路径，提交后仅供诊断，不能据此删除文件。

atomicFileResultObject.tempState #

absent / owned / delete-pending，表示本对象的临时文件状态。
close 成功后也可能 delete-pending：外部元数据句柄令系统延迟删除。再次 close 仅复核，不按路径删除。

atomicPreparedObject 成员列表 #

atomicPreparedObject.close() #

未提交：按原句柄标记删除并关闭；已提交：仅关闭句柄，不删除目标。
返回结果表；失败保留句柄供重试。可重复调用；GC 仅尽力兜底。

返回对象:atomicFileResultObject

atomicPreparedObject.commit() #

返回结果表。失败保留 prepared，可显式重试或 close。
committed=true 后绝不再次替换或回滚；ok=false 且 committed=true 仅表示后续清理失败。

返回对象:atomicFileResultObject

atomicPreparedObject.status() #

返回状态快照；不探查后来外部写入。对象仅在创建线程内使用，不可序列化传递。

返回对象:atomicFileResultObject

Markdown 格式