Document ExecutionContext locking strategy and thread-safety guarantees

Đang mở Phù hợp với người mới
  • Có gì không ổn?
#196 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 3 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
68/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Ít trao đổi
Công nghệ
python
Lĩnh vực
documentation

Hướng nghiên cứu

Đọc docs/HANDLER_AUTHORING.md và packages/darnit/src/darnit/core/models.py::ExecutionContext; issue cũng cho phép tạo docs/execution-context.md. Tài liệu hóa hành vi khóa và đồng thời, ngữ nghĩa khi xảy ra lỗi, khi nào nên hoặc không nên dùng bộ nhớ đệm, và các mẫu kiểm thử với context mới. Công việc hoàn tất khi hướng dẫn đề cập đủ cả năm điểm và khớp với phần triển khai.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

documentation module-core

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_func raises, 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:

  1. Locking strategy explanation — the double-checked locking pattern and why it's used (main lock fast-path + per-tool locks)
  2. Concurrency guarantees — what's serialized (same tool_key), what's parallel (different keys)
  3. Failure semantics — if run_func raises, is the lock released? (Yes, via with — but worth calling out.) Does the exception propagate? (Yes.) Is the key cached on failure? (No — only successful results are cached.)
  4. When to use vs not — cache expensive tool outputs (Scorecard, API queries); DON'T cache time-sensitive state (current time, fresh random numbers, etc.)
  5. 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)
Ngôn ngữ chính
Python
Star
22
Fork
27
Merge trung bình
4 ngày 20 giờ
Pull request đã merge (30 ngày)
75

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của darnitdevorg/darnit

Tất cả issue của darnitdevorg/darnit

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.