certflow.utils.retry module

SQLite 写操作退避重试工具

网络盘（坚果云等）上的 SQLite 文件在并发读写时极易出现 database is locked / database table is locked 错误。本项目里 UI 主线程（保存订正、写打印日志）与队列工作线程（写 print_jobs） 会同时访问同一个 .db 文件，普通 sqlite 引擎无 busy_timeout 时一旦撞车就直接抛锁异常。

本模块提供： - retry_on_locked()：对可调用对象做指数退避重试，专门消化瞬时写锁

（默认 12 次 / 上限 ~8s）。配合 certflow.utils.database 里的 WAL + busy_timeout PRAGMA 使用，可彻底消除打印流程中的写保护锁。

示例

>>> from certflow.utils.retry import retry_on_locked
>>> retry_on_locked(session.commit)

certflow.utils.retry.retry_on_locked(fn, *args, max_attempts=12, base_delay=0.05, max_delay=0.8, silent=False, **kwargs)

执行可调用对象，遇 SQLite 写锁则指数退避重试。

仅对写锁类异常（database is locked 等）重试；其他异常原样抛出。 适合包裹 session.commit() / session.flush() 这类幂等写库操作。

参数:

• fn (Callable[[...], T]) -- 待执行的可调用对象（如 session.commit）。

• **kwargs (*args /) --

  透传给 fn 的位置/关键字参数。

• max_attempts (int) -- 最大尝试次数（含首次），默认 12。

• base_delay (float) -- 初始退避秒数，默认 0.05。

• max_delay (float) -- 单次退避上限秒数，默认 0.8。

• silent (bool) -- 为 True 时连最后仍失败也吞掉异常返回 None（不推荐常开）。

• args (Any)

• kwargs (Any)

返回:

fn 的返回值。

返回类型:

T

示例

>>> retry_on_locked(session.commit)
>>> retry_on_locked(session.flush)

certflow.utils.retry.with_db_retry(max_attempts=12, base_delay=0.05, max_delay=0.8)

装饰器版本：把含写库的函数包进 retry_on_locked()。

示例

>>> @with_db_retry()
... def save(session):
...     session.commit()

参数:

• max_attempts (int)

• base_delay (float)

• max_delay (float)

返回类型:

Callable[[Callable[[...], T]], Callable[[...], T]]