From 324c7f236507e0545fa196be0eb41f069e31c5c6 Mon Sep 17 00:00:00 2001 From: Krylov Yaroslav Date: Sun, 30 Jul 2023 19:32:01 +0400 Subject: [PATCH] add initial version of propagation_engine.adoc --- doc/media/toposort_1.svg | 877 ++++++++++++++++++++++++++++++++++++ doc/propagation_engine.adoc | 45 ++ 2 files changed, 922 insertions(+) create mode 100644 doc/media/toposort_1.svg create mode 100644 doc/propagation_engine.adoc diff --git a/doc/media/toposort_1.svg b/doc/media/toposort_1.svg new file mode 100644 index 0000000..f4c0d3c --- /dev/null +++ b/doc/media/toposort_1.svg @@ -0,0 +1,877 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + x + b + c + a + + + + + + + + + + x + b + c + a + + + + + + + + + + x + b + c + a + + level 0 + level 1 + level 2 + + diff --git a/doc/propagation_engine.adoc b/doc/propagation_engine.adoc new file mode 100644 index 0000000..3052a70 --- /dev/null +++ b/doc/propagation_engine.adoc @@ -0,0 +1,45 @@ += Propagation engine +:toc: + +NOTE: The following is an adapted version of the articles +https://snakster.github.io/cpp.react/guides/engines/[Propagation engines] and +https://snakster.github.io/cpp.react/guides/engines/Toposort-engine.html[Toposort engine] +from the https://snakster.github.io/cpp.react/[cpp.react]'s documentation. + +The update propagation strategy is implemented by a propagation engine. + +Unlike its ancestor https://github.com/schlangster/cpp.react[cpp.react], `µReact` has inherited single propagation engine — sequential version of Toposort Engine. + +== Toposort engine + +=== Motivation + +Topological sorting of the graph nodes to decide on the update order is a common strategy among reactive programming implementations. +It can guarantee glitch freedom and update minimality. + +=== Concept + +To apply the topological sorting, each node is assigned a level, which is the maximum level of its predecessors plus 1. Nodes without any predecessors are at level 0. + +This figure shows how the update propagation proceeds in level iterations after a node has been changed: + +image::media/toposort_1.svg[toposort_1] + +=== Algorithm + +Toposort executes updates in the same thread that triggered the input. +It can be implemented with a priority queue that's ordered by node level, but to reduce the number of swaps, an improved algorithm is used: + +.... +Q = Successors of changed input nodes + +While Q is not empty: + P = {} + Find minimum level m in Q + Move nodes with level m from Q to P + Update nodes in P + Add successors of changed nodes to Q +.... + +`Q` contains all nodes that are scheduled to be updated eventually. `P` contains all nodes with the same level that are to be updated next. +Selecting and moving nodes from `Q` to `P` can be done efficiently by partitioning `Q`, which only has to be done once per iteration.