commitef9c996f24d5d3d0d73f5069052c575f3e5d34b6parent13161ba0ea1e3e21f5abcc1ba52aa6ee2e9430cdAuthor:Sol <sol@plunder.tech>Date:Wed, 7 Jun 2023 16:25:46 -0400 sire: bit docs + shallower _Nand / _Nor / _Xnor This patch cleans up the `02_bit.sire` docs and implements `_Nand`, `_Nor`, and `_Xnor` directly in terms of `_If` (instead of re-using `_And`, `_Or`, etc).Diffstat:

M | sire/02_bit.sire | | | 57 | +++++++++++++++++++++++++++++---------------------------- |

1 file changed, 29 insertions(+), 28 deletions(-)diff --git a/sire/02_bit.sire b/sire/02_bit.sire@@ -5,43 +5,44 @@ ### 02_bit <- 01_fan """ -""" Bits -""" ==== +""" Bits (Booleans) +""" =============== """ -""" These around foundational operations on bits/booleans. +""" This module defines the the foundational operations on bits +""" (booleans). """ -""" There's many different ways to implement these operations, optimizing -""" for different things. What I've decided to optimize for here is -""" "jet weight". """ -""" Jetting only `if` gets you pretty far. With an `if` jet + inlining, -""" everything else is automatically implemented as a truth table. +""" Jetting +""" ------- """ -""" We could instead optimize for dependency depth, having most of these -""" be implemented directly in terms of `2`, but `2` is much more -""" cumbersome than `if`. +""" All of the jets in this module are optional. """ -""" We could inline everything besides `if`, which would make all of -""" these functions literally truth tables. However, we instead optimize -""" for clarity of the PLAN code. +""" If implementing a subset of these jets, then _If is the highest +""" leverage, followed by _Bit and _Not. """ -""" The general principles are: """ -""" - Prefer fewer jets to shallow dependency trees. -""" - Prefer code clarity to shallow dependency trees +""" The `_If` Jet +""" ------------- """ -""" So in general, we are going for short/clear definitions that boil -""" down to a small set of core functions that benefit greatly from -""" jetting. +""" `_If` is a particularly important jet because, if the result is known +""" to be demanded, it can avoid creating thunks for both branches. """ +""" Consider something like the following: """ -""" Jetting -""" ------- +""" | _If (cond expr) (big "then" expr) (big "else" expr)) """ -""" All of the jets in this module are optional. +""" The naive behavior is to: """ -""" If implementing a subset of these jets, then _If is the highest -""" leverage, followed by _Bit and _Not. +""" 1. Construct thunks for all three arguments. +""" 2. Evaluate the condition thunk. +""" 3. Choose either the `then` or `else` branch. +""" 4. Evaluate that version. +""" +""" An optimized version can avoid constructing these thunks and just: +""" +""" 1. Evaluate the conditional expression. +""" 2. Choose a branch. +""" 3. Evalualte the expression for that branch. """ @@ -61,9 +62,9 @@ FALSE=0 = (_And x y) | _If x (_Bit y) 0 = (_Or x y) | _If x 1 (_Bit y) = (_Xor x y) | _If x (_Not y) (_Bit y) -= (_Nand x y) | _Not (_And x y) -= (_Nor x y) | _Not (_Or x y) -= (_Xnor x y) | _Not (_Xor x y) += (_Nand x y) | _If x (_Not y) 1 += (_Nor x y) | _If x 0 (_Not y) += (_Xnor x y) | _If x (_Bit y) (_Not y) """ Aliases and Syntax """""""""""""""""""""""""""""""""""""""""""""""""""""""""