From 969dcb8315c2af02dfec5bb489932d4e5fd060e2 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Thu, 18 Jan 2018 11:50:18 +1100 Subject: [PATCH] More docs --- docs/HyperlinkedInformation/Diffs.md | 16 ++++--- .../HyperlinkedInformation/UnchangedLayer2.md | 45 +++++++++++++++++++ 2 files changed, 55 insertions(+), 6 deletions(-) create mode 100644 docs/HyperlinkedInformation/UnchangedLayer2.md diff --git a/docs/HyperlinkedInformation/Diffs.md b/docs/HyperlinkedInformation/Diffs.md index 3c2dcf3..b98b9aa 100644 --- a/docs/HyperlinkedInformation/Diffs.md +++ b/docs/HyperlinkedInformation/Diffs.md @@ -7,17 +7,21 @@ labelled "Only Before" and "Only After". Enlightenment is nigh. currently in `app-db` or in a given subscription. While current values are good, you are often more interested to know how a value has been changed by the epoch. The value might start of as, say, `X` (before the event happened) but -ended up as `Y`. How are `X` and `Y` different, you wonder? +ended up as `X'`. How are `X` and `X'` different, you wonder? What got added or removed? What was modified? So, how then to display changes in a way that's easy to grok? I'm glad you asked. -`re-frame-trace` chooses to use the output of `(clojure.data/diff X Y)`. Remember -`X` is the before (original) value, and `Y` is the final value. +`re-frame-trace` chooses to do a calculation best shown by this pseudo code: +```clj +(let [[only-before only-after _] (clojure.data/diff X X')] + ...) +``` +Remember X is the value `before` (this epoch). And `X'` is the value `after` (the epoch has completed). By [looking at the docs](https://clojuredocs.org/clojure.data/diff) on `diff`, you'll see -that it returns a triple of values. `re-frame-trace` -displays the first two elements of this triple as "only before" and "only after" respectively. -The 3rd element is not very interesting because it tells us what hasn't changed, so it isn't shown. +that it calculates how two values differ, and returns a triple of values. `re-frame-trace` +captures and displays the first two elements of this triple as "only before" and "only after" +respectively. The 3rd element is not very interesting because it tells us what hasn't changed, so it isn't shown. To correctly interpret "Only Before" and "Only after", you'll need to spend a bit of time properly familiarising yourself with how `clojure.data/diff` works, but diff --git a/docs/HyperlinkedInformation/UnchangedLayer2.md b/docs/HyperlinkedInformation/UnchangedLayer2.md new file mode 100644 index 0000000..3a31328 --- /dev/null +++ b/docs/HyperlinkedInformation/UnchangedLayer2.md @@ -0,0 +1,45 @@ +## Unchanged Layer 2 Subscriptions + +This document briefly explains why `re-frame-trace` gives you an option to +ignore unchanged layer 2 subscriptions. + +### Background + +The `re-frame` docs +[make a distinction](https://github.com/Day8/re-frame/blob/master/docs/SubscriptionInfographic.md) +between `layer 2` and `layer 3` subscriptions: + - `layer 2` subscriptions extract data directly from `app-db` and should be + trivial in nature. There should be no computation in them beyond + what is necessary to extract a value from `app-db` + - `layer 3` subscriptions take values from `layer 2` nodes as inputs, and + compute a materialised view of those values. Just to repeat: they never directly + extract values from `app-db`. They create new values where necessary, and because of it + they to do more serious CPU hogging work. So we never want to run + `layer 3` subscriptions unless it is necessary. + +This structure delivers efficiency. You see, **all** (currently instantiated) `layer 2` subscriptions +will run **every** time `app-db` changes in any way. All of them. Every time. +And `app-db` changes on almost every event, so we want them to be computationally +trivial. + +If the value of a `layer 2` subscription tests `=` to its previous value, then the further +propagation of values through the signal graph will be pruned. +The more computationally intensive `layer 3` subscriptions, and ultimately +the views, will only recompute if and when there has been a change in their data inputs. + +We don't want your app recomputing views only to find that nothing has changed. + +### Back To Tracing + +Because `layer 2` subs run on every single modification of `app-db`, and because +very often nothing has changed, their trace can be a bit noisy. + +Yes, it happened, but it just isn't that interesting. + +So `re-frame-trace` gives you the option of filtering out trace for +the `layer 2` subscriptions where the value this time is the same as the +value last time. + +On the other hand, if a `layer 2` subscription runs and its value is +different to last time, that's potentially fascinating and ypou'll want to +be told all about it. :-)