luciano/telemere
1
0
Fork 0
mirror of https://github.com/taoensso/telemere.git synced 2025-12-16 09:31:11 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

[doc] Clarify that signal content is lazy

Browse source
This commit is contained in:
Peter Taoussanis 2025-11-28 09:59:35 +01:00
parent 125e006753
commit 917b1b408e
3 changed files with 21 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
imgs/signal-flow.svg
View file

File diff suppressed because one or more lines are too long
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 384 KiB

After

Width:  |  Height:  |  Size: 340 KiB

BIN
imgs/telemere.fig
View file

Binary file not shown.

12
main/resources/docs/signal-options.txt
View file

@ -9,12 +9,12 @@ All options are available for all signal creator calls:
Defaults to `:auto` for tracing signals, and nil otherwise
`:msg` --------- Arb app-level ?message to incl. in signal: str or vec of strs to join (with `\space`), may be a delay
`:data` -------- Arb app-level ?data to incl. in signal: usu. a map
`:data` -------- Arb app-level ?data to incl. in signal: usu. a map, LAZY! [3]
`:error` ------- Arb app-level ?error to incl. in signal: platform error [2]
`:run` --------- ?form to execute UNCONDITIONALLY; will incl. `:run-val` in signal
`:do` ---------- ?form to execute conditionally (iff signal allowed), before establishing `:let` ?binding
`:let` --------- ?bindings to establish conditionally (iff signal allowed), BEFORE evaluating `:data` and `:msg` (useful!)
`:do` ---------- ?form to execute conditionally (iff signal allowed) and LAZILY [3], before establishing `:let` ?binding
`:let` --------- ?bindings to establish conditionally (iff signal allowed) and LAZILY [3], BEFORE evaluating `:data` and `:msg` (useful!)
`:parent` ------ Custom ?{:keys [id uid]} to override auto (dynamic) parent signal tracing info
`:root` -------- Custom ?{:keys [id uid]} to override auto (dynamic) root signal tracing info
@ -37,9 +37,13 @@ All options are available for all signal creator calls:
<kvs> ---------- Other arb app-level ?kvs to incl. in signal. Typically NOT included in
handler output, so a great way to provide custom data/opts for use
(only) by custom transforms/handlers.
(only) by custom transforms/handlers. LAZY! [3]
If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
[1] `java.time.Instant` or `js/Date`
[2] `java.lang.Throwable` or `js/Error`
[3] Most Telemere signal content is evaluated CONDITIONALLY (iff signal allowed),
LAZILY (when signal is created), and on the HANDLING THREAD (not logging thread).
This allows efficient filtering, better control+monitoring of back pressure,
conditional effects, etc. Ref. <https://www.taoensso.com/telemere/flow> for visual!