Differences

This shows you the differences between two versions of the page.

--- notes:internals:db [2025/09/07 01:13] – smj-edison
+++ notes:internals:db [2025/09/08 19:27] (current) – smj-edison
@@ Line 1: / Line 1: @@
-====== Database ======
+====== Database (folk2) ======
 //If you want to follow along in the code, all of these things are implemented in trie.c, db.c, folk.c,
 and prelude.tcl.//
-Folk's database stores all Wishes, Claims, Whens, and Holds. Essentially, it stores everything that happens
+Folk's database stores all Wishes, Claims, and Whens. Essentially, it stores everything that happens
-in Folk. The database works with Statements, either inserting or removing them. All those verbs I mentioned—
+in Folk. The data type of this database is a Statement. Statements are inserted when calling
-Wish, When, etc—are functions that insert a Statement into the database by calling the Say function.
+Wish, Claim, and When.
-We'll cover Statement removal later.
 ===== Statements =====
 So, what is a Statement? A Statement consists of two parts: the Clause and the child matches*.
-Let's start with the Clause: a Clause is an array of words, with each word known as a Term. An example
+Let's start with the Clause: a Clause is an array of words, with each word known as a Term†. An example
 Clause, "the sky is blue", would become ["the", "sky", "is", "blue"]. We'll cover child matches in a bit.
-=== Wish and Claim ===
+=== Wishes and Claims ===
-Let's see what happens when we run Wish.
+Statements are inserted when running the core commands—Wish, Claim, and When—by calling a command called
+Say. Say inserts the provided Statement into the database.
+Since Wish is a command that inserts a Statement, let's see what happens when we run it.
 <code>Wish the sky is blue</code>
@@ Line 37: / Line 39: @@
   - We add "when" to the beginning, so the database knows this is a When.
   - We preserve both the query and the code (that's the "the sky is /color/ { # code here }" part).
-  - We add "with environment {foo bar}", as Tcl doesn't capture scopes. We manually capture the parent scope instead (containing the variable "foo" with the value of "bar"). We'll use this to execute the When later.
+  - We add "with environment {foo bar}"‡, as Tcl doesn't capture scopes. We manually capture the parent scope instead (containing the variable "foo" with the value of "bar"). We'll use this to execute the When later.
 ==== Reacting to Statements ====
@@ Line 57: / Line 59: @@
 Wait wait, what?? That was a lot all at once. Let's break it down.
-First, back to the context. We just inserted a Statement, so we need to check if there's any existing
+First, the context. We just inserted a Statement, so we need to check if there's any existing
 Whens that match. So, we do a database query. But what kind of query? Well, let's convert this Wish into
 what a When would look like for this Statement. The easiest way to explain this is to just look at a
@@ Line 74: / Line 76: @@
 === When scheduling ===
-One exciting thing about folk2 is its support for multithreading. It does this by running each When
+One exciting thing about folk2 is its support for multithreading. It supports this by scheduling each When
-on its own thread. That means that when a Statement matches with a When, it needs to be queued for the next
+to run on a thread pool. That means that when a Statement matches with a When, it needs to be queued for the next
 available thread to pick it up. That's exactly what happened in this example. The Wish got inserted,
 it checked for matching Whens, and then when it found a match, it pushed it to the work queue to be run
 as soon as a thread is available.
-In fact, it's quite literally called a Match in Folk. When a When Statement gets pulled from the queue,
+In fact, when this queued item runs, it is known as a Match. This Match contains a list of child
-it creates a Match before it runs the When body.
+statements, which we'll get to in a bit.
 === Statements and Matches ===
@@ Line 131: / Line 133: @@
 First off, we'll look at its children, which is really just one child in this case.
 {{notes:internals:statement-removal-1.jpg?600|}}
 We'll go ahead and remove that Match.
 {{notes:internals:statement-removal-2.jpg?600|}}
 In the process, we'll also note that that Match also had a child Statement, and we'll remove that too:
 {{notes:internals:statement-removal-3.jpg?600|}}
@@ Line 154: / Line 159: @@
 === Footnotes ===
-* Also metadata, but this is already long enough.
+* Also metadata and keep time, but this article is already long enough.
+† This is a little misleading, as a Statement can have Terms with spaces in them. For example,
+the last Term in `Wish $this has name "Mason Jones"` has spaces in it. It's just that in Tcl, lists are
+space seperated by default, and all the database commands are called from Tcl.
+‡ This is simplified for explanation reasons. This is actually a list of environments, with each
+entry being one level higher in the call stack.