Document ExecutionContext locking strategy and thread-safety guarantees
维护者通常 3 天内回复
还没有人认领这个 Issue。
评估
- 难度
- 2/5
- 预计耗时
- 1-3 小时
- 新手友好度
- 68/100
- Issue 类型
- 文档
- 描述清晰度
- 描述清楚
- 活跃度
- 冷清
- 技术栈
- python
调研方向
阅读 docs/HANDLER_AUTHORING.md 和 packages/darnit/src/darnit/core/models.py::ExecutionContext；issue 也允许创建 docs/execution-context.md。说明锁定和并发行为、失败语义、何时使用或避免缓存，以及使用新 context 的测试模式。指南涵盖全部五点并与实现一致，即为完成。
由索引模型根据 Issue 内容生成。
描述
Context
#189 added ExecutionContext with a thoughtful double-checked locking design, but the strategy isn't documented beyond code comments. Handler authors using get_or_run_tool() need to understand:
- What guarantees does the context provide? (same key → same result within an audit run)
- What happens under concurrent access? (different keys parallel, same key serialized)
- What can go wrong? (e.g., if
run_funcraises, is the lock released properly?) - When should handlers NOT use this? (e.g., tool output is non-deterministic or time-sensitive)
What to document
Extend docs/HANDLER_AUTHORING.md (or create a dedicated docs/execution-context.md) with:
- Locking strategy explanation — the double-checked locking pattern and why it's used (main lock fast-path + per-tool locks)
- Concurrency guarantees — what's serialized (same
tool_key), what's parallel (different keys) - Failure semantics — if
run_funcraises, is the lock released? (Yes, viawith— but worth calling out.) Does the exception propagate? (Yes.) Is the key cached on failure? (No — only successful results are cached.) - When to use vs not — cache expensive tool outputs (Scorecard, API queries); DON'T cache time-sensitive state (current time, fresh random numbers, etc.)
- Testing patterns — how to test handlers that use ExecutionContext (fixture that provides a fresh context per test)
References
- Infrastructure:
packages/darnit/src/darnit/core/models.py::ExecutionContext - Existing usage guide:
docs/HANDLER_AUTHORING.md(brief "Shared Execution Context" section added in #189) - Related: #193 (audit cache documentation — similar pattern)
- 主要语言
- Python
- 星标
- 22
- 派生
- 27
- 平均合并
- 4 天 20 小时
- 30 天内合并 PR
- 75
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
darnitdevorg/darnit 的其他 Issue
-
ci needs triage
难度 2/5 1-3 小时 新手友好度 62/100
darnitdevorg/darnit#607 ·
维护者通常 3 天内回复
-
good first issue maintenance
难度 2/5 1-3 小时 新手友好度 83/100
darnitdevorg/darnit#587 · 2 条评论 ·
维护者通常 3 天内回复
-
Container image has no zizmor, so OSPS-AC-04.02 always reports missing_tool可能已有人在做 @mlieberman85 于 20 天前认领。 未关闭infrastructure module-baseline
难度 2/5 1-3 小时 新手友好度 65/100
darnitdevorg/darnit#585 · 1 条评论 ·
维护者通常 3 天内回复
-
module-baseline
难度 2/5 1-3 小时 新手友好度 76/100
darnitdevorg/darnit#344 · 1 条评论 ·
维护者通常 3 天内回复
-
module-core
难度 2/5 1-3 小时 新手友好度 78/100
darnitdevorg/darnit#195 ·
维护者通常 3 天内回复
查看 darnitdevorg/darnit 的全部 Issue
相似的 Issue
-
docs size:S
难度 1/5 1 小时以内 新手友好度 88/100
维护者通常 1 天内回复
-
documentation
难度 2/5 1-3 小时 新手友好度 78/100
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 74/100
strawberry-graphql/strawberry#4794 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 78/100
dataforgoodfr/cetolog#21 ·
-
难度 2/5 1-3 小时 新手友好度 76/100
btclib-org/btclib#2932 ·
维护者通常 1 天内回复