From 78023da68418bc401cac6f58fc31b9d623d03191 Mon Sep 17 00:00:00 2001 From: jdonszelmann Date: Mon, 12 Aug 2024 17:55:58 +0200 Subject: [PATCH 1/3] improve query system documentation --- src/queries/incremental-compilation-in-detail.md | 4 +++- src/queries/incremental-compilation.md | 14 ++++++++++++++ src/queries/query-evaluation-model-in-detail.md | 6 +++--- 3 files changed, 20 insertions(+), 4 deletions(-) diff --git a/src/queries/incremental-compilation-in-detail.md b/src/queries/incremental-compilation-in-detail.md index a98e4990f..775727b7b 100644 --- a/src/queries/incremental-compilation-in-detail.md +++ b/src/queries/incremental-compilation-in-detail.md @@ -186,7 +186,9 @@ By using red-green marking we can avoid the devastating cumulative effect of having false positives during change detection. Whenever a query is executed in incremental mode, we first check if its already green. If not, we run `try_mark_green()` on it. If it still isn't green after that, then we actually -invoke the query provider to re-compute the result. +invoke the query provider to re-compute the result. Re-computing the compute might +then itself involve recursively invoking more queries, which can mean we come back +to the `try_mark_green()` algorithm for the dependencies recursively. ## The Real World: How Persistence Makes Everything Complicated diff --git a/src/queries/incremental-compilation.md b/src/queries/incremental-compilation.md index abef144d7..c2c195a4a 100644 --- a/src/queries/incremental-compilation.md +++ b/src/queries/incremental-compilation.md @@ -21,6 +21,20 @@ not a general graph). [DAG]: https://en.wikipedia.org/wiki/Directed_acyclic_graph +> **NOTE**: You might think of a query as simply the definition of a query. +> A thing that you can invoke, a bit like a function, +> and which either returns a cached result or actually executes the code. +> +> If that's the way you think about queries, +> it's good to know that in the following text, queries will be said to have colours. +> Keep in mind though, that here the word query also refers to a certain invocation of +> the query for a certain input. As you will read later, queries are fingerprinted based +> on their arguments. The result of a query might change when we give it one argument +> and be coloured red, while it stays the same for another argument and is thus green. +> +> In short, the word query is here not just used to mean the definition of a query, +> but also for a specific instance of that query with given arguments. + On the next run of the compiler, then, we can sometimes reuse these query results to avoid re-executing a query. We do this by assigning every query a **color**: diff --git a/src/queries/query-evaluation-model-in-detail.md b/src/queries/query-evaluation-model-in-detail.md index 296d88f6e..0e8b9bcaf 100644 --- a/src/queries/query-evaluation-model-in-detail.md +++ b/src/queries/query-evaluation-model-in-detail.md @@ -174,9 +174,9 @@ Since query providers are regular functions, this would behave much as expected: Evaluation would get stuck in an infinite recursion. A query like this would not be very useful either. However, sometimes certain kinds of invalid user input can result in queries being called in a cyclic way. The query engine includes -a check for cyclic invocations and, because cycles are an irrecoverable error, -will abort execution with a "cycle error" messages that tries to be human -readable. +a check for cyclic invocations of queries with the same input aguments. +And, because cycles are an irrecoverable error, will abort execution with a +"cycle error" messages that tries to be human readable. At some point the compiler had a notion of "cycle recovery", that is, one could "try" to execute a query and if it ended up causing a cycle, proceed in some From c12c06ded7cc7edb891ece53d9b0e29b89206b27 Mon Sep 17 00:00:00 2001 From: jdonszelmann Date: Mon, 19 Aug 2024 11:52:00 +0200 Subject: [PATCH 2/3] fix typo messages => message --- src/queries/query-evaluation-model-in-detail.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/queries/query-evaluation-model-in-detail.md b/src/queries/query-evaluation-model-in-detail.md index 0e8b9bcaf..80b5f4928 100644 --- a/src/queries/query-evaluation-model-in-detail.md +++ b/src/queries/query-evaluation-model-in-detail.md @@ -176,7 +176,7 @@ be very useful either. However, sometimes certain kinds of invalid user input can result in queries being called in a cyclic way. The query engine includes a check for cyclic invocations of queries with the same input aguments. And, because cycles are an irrecoverable error, will abort execution with a -"cycle error" messages that tries to be human readable. +"cycle error" message that tries to be human readable. At some point the compiler had a notion of "cycle recovery", that is, one could "try" to execute a query and if it ended up causing a cycle, proceed in some From 337ba39f76ab2bf3b8ffe5267198815807a73d93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonathan=20D=C3=B6nszelmann?= Date: Fri, 6 Sep 2024 15:47:11 +0200 Subject: [PATCH 3/3] Update src/queries/incremental-compilation-in-detail.md Co-authored-by: lcnr --- src/queries/incremental-compilation-in-detail.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/queries/incremental-compilation-in-detail.md b/src/queries/incremental-compilation-in-detail.md index 775727b7b..b7f475620 100644 --- a/src/queries/incremental-compilation-in-detail.md +++ b/src/queries/incremental-compilation-in-detail.md @@ -186,7 +186,7 @@ By using red-green marking we can avoid the devastating cumulative effect of having false positives during change detection. Whenever a query is executed in incremental mode, we first check if its already green. If not, we run `try_mark_green()` on it. If it still isn't green after that, then we actually -invoke the query provider to re-compute the result. Re-computing the compute might +invoke the query provider to re-compute the result. Re-computing the query might then itself involve recursively invoking more queries, which can mean we come back to the `try_mark_green()` algorithm for the dependencies recursively.