Document ExecutionContext locking strategy and thread-safety guarantees

Offen Anfängerfreundlich
  • Stimmt etwas nicht?
#196 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 3 Tagen

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
2/5
Geschätzter Aufwand
1-3 Stunden
Anfängerfreundlichkeit
68/100
Issue-Typ
Dokumentation
Klarheit
Klar beschrieben
Aktivitätsstatus
Ruhig
Tech-Stack
python
Bereich
documentation

Rechercherichtung

Lies docs/HANDLER_AUTHORING.md und packages/darnit/src/darnit/core/models.py::ExecutionContext; das Issue erlaubt außerdem, docs/execution-context.md anzulegen. Dokumentiere das Sperr- und Nebenläufigkeitsverhalten, die Fehlersemantik, wann Caching verwendet oder vermieden werden sollte, und Testmuster mit frischen Contexts. Fertig ist die Arbeit, wenn der Leitfaden alle fünf Punkte behandelt und mit der Implementierung übereinstimmt.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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)
Vorherrschende Sprache
Python
Sterne
22
Forks
27
Ø Merge
5 T. 2 Std.
Gemergte PRs (30 T.)
78

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus darnitdevorg/darnit

Alle Issues in darnitdevorg/darnit

Ähnliche Issues

Weitere Issues zu Python

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.