bool-hybrid-array 的 ofstream/ifstream 文件流实测:操纵符、读写往返与分批落盘边界

大家应该都知道 bool-hybrid-array 吧?我之前用它主要盯着布尔数组、稀疏稠密那一套,这轮换口味翻源码的时候才注意到,这个包里还跟着一套长得很像 C++ iostream 的文件流实现:ofstream、ifstream、fstream、filebuf,再加上 cout、cin、endl、flush 和一堆 setw、setprecision、setfill 这样的操纵符。一个好程序员应该知道一下这些——哪怕最后不拿它写生产日志,搞清楚它在本机到底能写到什么程度、哪些地方会掉链子,选型的时候心里也有底。这轮我把这套流在本机冷进程里从头跑了一遍,环境是 Python 3.12.11、numpy 2.5.5、bool-hybrid-array 9.13.12,许可证是 Apache-2.0 OR MulanPSL-2.0 双许可。下面出现的耗时、字节数、读回内容和报错栈,全部来自这一轮实跑的输出,不沿用旧版本的口径。

一、先把这套流开放了哪些对象摆清楚

翻 bool_hybrid_array/_cppiostream.py 这个模块,对外能直接拿到的流类型和工具大体是这么几类:

  • 输入侧:istream 基类,以及从它派生的 ifstream(文件只读)、fstream(读写两用);顶层还有一个 cin 输入对象。
  • 输出侧:ostream 基类,派生 ofstream(文件只写)、fstream(读写两用);顶层有一个 cout 输出对象。
  • 缓冲层:filebuf,负责打开文件、mmap 映射、逐字符 put_char/get_char、seekg/seekp、tellg/tellp 和 flush/close。
  • 操纵符:endl、flush,以及 boolalpha、showbase、showpoint、uppercase、showpos、fixed、scientific、left、right、internal、setw、setprecision、setfill、ignore 这一组,每个都是 Manipulator 实例,被流用 << 推入时回调对应方法改流的格式标志。

写法上刻意贴近 C++:输出用 << 把数据或操纵符依次推进去,输入用 >> 把值读到目标对象里。目标类型支持 ctypes 标量、numpy 标量或数组,以及任何带 __cin__ 方法的对象——库里的 BHA_string 就实现了 __cin__,可以直接被文件流读进来。

二、第一个能跑通的片段:一次性写入再读回

我先从最朴素的用法试起:用 ofstream 打开一个临时文件,写入一段文本和几个数值,close 之后再用 ifstream 逐行 getline 读回来。

import os
from bool_hybrid_array import ofstream, ifstream, endl, setw, setfill

p = "io_demo.txt"
if os.path.exists(p):
    os.remove(p)

o = ofstream(p)
print("is_open:", o.is_open())
print("default flags:", o.format_flags, "precision:", o.precision, "fill:", repr(o.fill_char))

o << "score=" << 97 << endl
o.close()

raw = open(p, "rb").read()
print("file bytes:", len(raw))
print("repr:", repr(raw.decode("utf-8", errors="replace")))

i = ifstream(p)
print("good:", i.good(), "eof:", i.eof(), "fail:", i.fail(), "rdstate:", i.rdstate())
print("read line:", repr(i.getline("\n")))
i.close()

这一轮本机跑出来的初始状态是:is_open: True,默认格式标志 flags: 17,精度 precision: 6,填充字符 fill: ' '。文件写完读回来,第一行 score=97 是正常落盘的;ifstream 刚打开时 good: True、eof: False、fail: False、rdstate: 0,读完一行走到文件尾之后 eof: True、good: False,状态位的行为和 C++ 流的那套 goodbit/eofbit/failbit/badbit 是对应的。

单看这一段,一次性把内容写进文件、再关掉流落盘,路线是通的。问题出在我接着往文件里写第二行、第三行的时候。

三、操纵符在输出侧的实际表现

在正式踩坑之前,我先把格式操纵符挨个过了一遍,确认哪些在 9.13.12 是真生效的。ostream 的格式化逻辑集中在 _format_num 里:布尔按 boolalpha 决定输出 true/false 还是 1/0;整数按 dec/hex/oct 选进制,showbase 加前缀,uppercase 转大写,showpos 给正数加 +;浮点按 fixed/scientific/g 选格式,precision 控制位数,showpoint 在没有小数点时补一个 .;setw 只对下一次输出生效,left/right/internal 决定补位方向,setfill 给补位字符。

from bool_hybrid_array import (ofstream, endl, setw, setprecision, setfill,
                                left, right, fixed, showpos, showpoint)

o = ofstream("fmt.txt")
o << "ratio=" << 3.14159 << endl
o << "flag=" << True << endl
o << setw(10) << setfill('*') << "x" << endl
o << right << setw(8) << setfill(' ') << 42 << endl
o << fixed << setprecision(3) << 2.71828 << endl
o << showpos << 5 << endl
o.close()

顶层 cout 走的是同一套 _format_num,区别只是输出目标换成标准输出。我单独验证了一次宽度和填充:

from bool_hybrid_array import cout, setw, setfill, endl
cout << "cout check: " << setw(6) << setfill('-') << 7 << endl

本机这一句打印出来是 cout check: -----7:数字 7 右对齐,宽度 6,补位字符 -,一共 5 个横杠加一个 7。setw 用完即复位、setfill 保留到下一次 setfill 覆盖,这两点和 C++ 的约定一致。fixed 配 setprecision 会把浮点按定点小数截到指定位数,showpos 会给正数补上 +,showpoint 强制带出小数点。这一组操纵符在格式化展示上是能用的。

为了把其余几个操纵符也确认一遍,我避开分批 endl 的干扰,每个样本单独开一个 ofstream 文件、一次性写入后 close 落盘,再把文件内容读回来:

def one(name, build):
    o = ofstream(name)
    build(o)
    o.close()

one("f_boolalpha.txt", lambda o: o << boolalpha << True << "/" << False)
one("f_booldefault.txt", lambda o: o << noboolalpha << True << "/" << False)
one("f_sci.txt", lambda o: o << scientific << setprecision(4) << 0.00012345)
one("f_left.txt", lambda o: o << left << setw(10) << setfill('.') << "ab")
one("f_showpos.txt", lambda o: o << showpos << 42)
one("f_showpoint.txt", lambda o: o << showpoint << 3.0)

六个样本本机读回的结果:

操纵符组合 输入 读回内容 字节数
boolalpha True / False true/false 10
noboolalpha(默认) True / False 1/0 3
scientific + precision(4) 0.00012345 1.2345e-04 10
left + setw(10) + fill('.') "ab" ab........ 10
showpos 42 +42 3
showpoint 3.0 3. 2

可以看到布尔在 boolalpha 下输出英文单词、默认输出 1/0;科学计数法按指定位数输出 e 格式;左对齐时补位字符填在内容右侧;showpos 给正数加正号;showpoint 让整数形式的浮点也保留小数点。需要留意的是,这一轮模块对外导出的操纵符里没有单独的 hex、oct 进制切换器,进制相关的格式标志只在内部常量层提供,文章里就不把十六进制、八进制输出当成可用接口来写。

四、踩坑现场:每条 endl 分批写,后续内容落盘成 NUL

真正让我停下来仔细看的,是分批写入这一段。我最初想当然地按 C++ 的习惯,每条记录后面跟一个 endl,以为 endl 只是换个行顺手 flush 一下,结果打开文件一看,第一条后面全是 \x00。

为了把现象分清楚,我写了四个对照样本,分别控制"有没有 endl、flush 几次":

# A: 无 endl,连续多段,close 时一次性落盘
o = ofstream("ioA.txt")
o << "aaa" << "bbb" << "ccc"
o.close()

# B: 每条 endl(endl 内部会 flush)
o = ofstream("ioB.txt")
o << "line1" << endl
o << "line2" << endl
o << "line3" << endl
o.close()

# C: 手动 flush 两次
o = ofstream("ioC.txt")
o << "x1" << endl
o.flush()
o << "x2" << endl
o.flush()
o.close()

# D: 单条长串
o = ofstream("ioD.txt")
o << "single-line-0123456789"
o.close()

四个文件本机读回的字节和内容如下:

样本 写入方式 文件字节 读回内容
A 无 endl,三段连续,close 一次性 flush 9 aaabbbccc
B 三条各跟 endl(内部 flush) 21 line1\r\n 后接 14 个 \x00
C 两条各 endl + 手动 flush 8 x1\r\n 后接 4 个 \x00
D 单条长串,一次写入 22 single-line-0123456789

对照下来规律很明确:不触发 flush、攒到 close 一次性落盘的 A 和 D,内容完整;只要中间经过 endl 或手动 flush,flush 之后再写进去的字符就在文件里变成了 NUL 字节。B 里 line2、line3 整个没了,C 里 x2 整个没了,剩下的位置用零填充到当前文件大小。

这里有两个细节值得记一笔。第一,endl 写的是 \r\n(回车加换行),不是原生 Python 文本里常用的 \n,所以即便内容写全,和原生 open 写出的文本在换行符上也不完全一样。第二,文件大小本身是对的——put_char 时维护了 _file_size,close 时按这个大小截断,所以 NUL 占住了本该属于后续内容的位置,文件不会变短,只是内容是空的。

五、文件流状态位和打不开的文件

输入流的状态位是按 goodbit、eofbit、failbit、badbit 四个标志组合的,rdstate 返回位掩码。我试了一个不存在的文件路径:

miss = ifstream("no_such_147.txt")
print("is_open:", miss.is_open(), "good:", miss.good(), "fail:", miss.fail())

本机结果是 is_open: False、good: False、fail: True。filebuf.open 打不开文件时会把自己置空并返回 False,ifstream 随即 setstate(failbit)。读到文件尾时 eofbit 置位,good() 返回 False,但 fail() 不一定为 True——前面第二节读单行样本就是这个状态:eof 为真、fail 为假。

getline 默认以换行符为分隔、上限 4096 字符,读到分隔符或 EOF 为止,返回解码后的字符串。文件里没有换行符、一次读到头时,读完 good 就变 False,这属于正常到尾,不是写入失败。

六、BHA_string 被文件流读进来,以及 fstream 读写

库里的 BHA_string 实现了 __cin__,所以可以直接被 >> 读。我先写一个文件,再用 ifstream 把内容读进 BHA_string:

from bool_hybrid_array import ofstream, ifstream, BHA_string, endl

o2 = ofstream("io_str.txt")
o2 << "hello-bha-string" << endl
o2.close()

s = BHA_string("")
i2 = ifstream("io_str.txt")
i2 >> s
print("read back:", str(s), "len:", len(s), "eq:", str(s) == "hello-bha-string")
i2.close()

本机读回 hello-bha-string,长度 16,和原生字符串比较相等。这一条路线是通的:文件里的文本经过 __cin__ 写进 BHA_string 内部的 bytearray,解码用 utf-8、errors 替换。

fstream 是读写两用,构造时按 in|out 打开,文件存在走 r+b、不存在走 w+b。我试了同一个文件先写再回读:

f = fstream("io_rw.txt")
f << "abc123" << endl
f.flush()
f.seekg(0)
back = f.getline("\n")
print("roundtrip:", back, "match:", back == "abc123")
f.close()

这一轮本机 roundtrip 读回和原串 abc123 比对 match: False。结合第四节的现象,问题同样出在写入中途 flush 之后缓冲区没有被正确回写,读写复用同一个 filebuf 时,刚 flush 过的位置读到的不是刚写进去的内容。

七、五千条记录的批量基准:耗时和字节数对照

单条样本看不出量级差距,我把记录数拉到 5000 条,分别用 ofstream 和原生 open/write 各跑 5 次取中位,对比耗时、文件字节数和逐行一致性。

import time, statistics, os

N = 5000

def bha_write():
    p = "bench_bha.txt"
    if os.path.exists(p): os.remove(p)
    w = ofstream(p)
    for k in range(N):
        w << "row=" << k << ",v=" << (k * 1.5) << endl
    w.close()

def native_write():
    p = "bench_native.txt"
    if os.path.exists(p): os.remove(p)
    with open(p, "w", encoding="utf-8") as w:
        for k in range(N):
            w.write(f"row={k},v={k*1.5}\n")

本机 5 次中位耗时和结果:

写入方式 5000 条中位耗时 文件字节数 行数 逐行与原生比对
ofstream 分批 endl 15075.6736 ms 88149 5000 不一致(含 NUL 与 \r\n)
原生 open/write 8.2121 ms 88149 5000 基准

字节数两边都是 88149,行数都是 5000,但逐行比对 exact match: False。耗时上,ofstream 这条路径中位 15075.67 毫秒,原生 open/write 中位 8.21 毫秒,前者大约是后者的 1835.8 倍。慢的来源主要在两个地方:一是每个字符都走一次 put_char 落到 mmap 位置、维护位置和文件大小,二是每条 endl 都触发一次 flush,flush 里又做 mmap flush、文件 truncate 和文件 flush。这轮样本里 5000 条就触发了 5000 次 flush,和第四节观察到的 NUL 现象是同一条缓冲路径上的问题。

八、关于 NUL 现象的本机观察

把 filebuf 的实现捋一遍,这轮观察到的现象大致可以这样描述:写模式打开文件时,filebuf 用 mmap 把文件映射出来,写模式下按至少 4096 字节截断并映射;put_char 往当前位置写一个字节,位置超过当前文件大小时更新文件大小。flush 时会把 mmap 刷盘、再按当前 _file_size 把文件截断、刷新文件句柄。

问题在于 flush 截断文件之后,已经建立的 mmap 映射没有随之重新调整,下一轮 put_char 继续往映射区后续位置写,这部分写入在 close 再次截断时没有作为有效内容保留下来,于是中间留下一段 NUL。这是我对照源码和四组样本观察到的对应关系;具体到不同平台、不同 mmap 实现上的表现,建议在自己的目标环境再用真实样本复核,不要直接把这段根因分析当成库的官方结论。

需要强调的是,这一节说的是 9.13.12 本机冷进程里跑出来的表现,不代表其他版本、其他平台上一定相同;如果后续版本改了缓冲回写逻辑,以当时本机实跑结果为准。

九、这套流适合放在什么位置

把这轮实测收敛成几条能落地的判断。

第一,一次性构造好一段内容、close 时统一落盘的场景,ofstream 是能写通的:A、D 两组样本内容完整,BHA_string 也能通过 >> 从文件读回来,操纵符在宽度、填充、精度、对齐这些格式化诉求上都有对应接口。如果你只是想在一个 Python 项目里用 << 这种写法生成一份静态文本或配置片段,这条路径可以试。

第二,需要高频分批 flush 的场景,这轮实测不建议拿它做主写路径。每条记录都跟 endl 的日志、流水、增量落盘场景,既会触发第四节的 NUL 落盘问题,批量耗时也和原生 open/write 差了三个数量级;这种需求直接用原生 open(..., "a", encoding="utf-8") 写文本,或者用标准库的 logging、csv、json 模块,在这轮基准里明显更稳更快。

第三,读侧的状态位、getline、BHA_string 回读这些接口语义是清楚的,不存在打不开文件还报 good 的情况;但读写复用同一个 fstream、中途多次 flush 的组合,这轮没有拿到和原串一致的回读结果,用之前先用自己的样本跑一遍往返校验。

选型时可以按写入节奏分三种情况对号入座。内容在内存里拼好、最后一次性写文件,想要 << 链式写法做格式化展示,可以用 ofstream;边产生边落盘、频繁追加刷新的日志或流水,用原生文本写入;需要结构化持久化布尔数组或混合记录,库里的 Create_BHA/Ask_BHA、BHAX_Descriptor 那条序列化路线和文件流是两套独立机制,不要混在一起比较。

bool-hybrid-array 9.13.12 把一套 C++ 风格的流接口带进了 Python 侧,操纵符、状态位、文件缓冲和 __cin__ 接入都有对应实现;这轮五千条批量写入和四组分批样本的实测数字也如实摆在这里,它更适合一次性格式化落盘的轻量场景,高频分批 flush 的生产日志仍应优先选原生文件接口。实际用之前,按自己的数据规模和写入节奏在本机跑一轮往返校验,再决定要不要把这套流接进项目。

posted @ 2026-11-22 10:13  贝壳bkshell  阅读(3)  评论(0)    收藏  举报