UIP-0103: Persistent Nock Caching (#496)

Implements
[UIP-0103](https://github.com/urbit/UIPs/blob/main/UIPS/UIP-0103.md).

TODO: Write a roadmap for merging this. What else has to be done?
- [x] Loom migration
- [x] Affordance for future specialized caches in `u3a_road` struct
- [x] PRs for use cases ready in Arvo
  - [x] urbit/urbit#6770
  - [x] urbit/urbit#6773
  - [x] ~~Ford Lightning~~
- [x] Manage new persistent state like we manage the rest of our
persistent state (`|mass` breaks before we do this)
- [x] Update command-line args for cache sizes
- [x] Determine why `bazel build //pkg/vere:test-fake-ship` seems to
hang indefinitely (I ran it for ~16h on my own dedicated box and it
still didn't finish)

Tested working in all vanes I tested (Iris, etc. are a little more
cumbersome):
- [x] Ames
- [x] Arvo
- [x] Behn
- [x] Clay
- [x] Dill
- [x] Eyre
- [x] Gall

pkg/noun/allocate.c

@@ -2131,7 +2131,8 @@ u3a_mark_road(FILE* fil_u)
   tot_w += u3a_maid(fil_u, "  profile batteries", u3a_mark_noun(u3R->pro.don));
   tot_w += u3a_maid(fil_u, "  profile doss", u3a_mark_noun(u3R->pro.day));
   tot_w += u3a_maid(fil_u, "  new profile trace", u3a_mark_noun(u3R->pro.trace));
-  tot_w += u3a_maid(fil_u, "  memoization cache", u3h_mark(u3R->cax.har_p));
+  tot_w += u3a_maid(fil_u, "  transient memoization cache", u3h_mark(u3R->cax.har_p));
+  tot_w += u3a_maid(fil_u, "  persistent memoization cache", u3h_mark(u3R->cax.per_p));
   return   u3a_maid(fil_u, "total road stuff", tot_w);
 }
 
@@ -2158,6 +2159,7 @@ u3a_rewrite_compact(void)
   u3a_rewrite_noun(u3R->pro.day);
   u3a_rewrite_noun(u3R->pro.trace);
   u3h_rewrite(u3R->cax.har_p);
+  u3h_rewrite(u3R->cax.per_p);
 
   u3R->ski.gul = u3a_rewritten_noun(u3R->ski.gul);
   u3R->bug.tax = u3a_rewritten_noun(u3R->bug.tax);
@@ -2166,6 +2168,7 @@ u3a_rewrite_compact(void)
   u3R->pro.day = u3a_rewritten_noun(u3R->pro.day);
   u3R->pro.trace = u3a_rewritten_noun(u3R->pro.trace);
   u3R->cax.har_p = u3a_rewritten(u3R->cax.har_p);
+  u3R->cax.per_p = u3a_rewritten(u3R->cax.per_p);
 }
 
 /* _ca_print_box(): heuristically print the contents of an allocation box.

pkg/noun/allocate.h

@@ -154,11 +154,11 @@
 
         u3a_jets jed;                         //  jet dashboard
 
-        struct {                              // bytecode state
-          u3p(u3h_root) har_p;                // formula->post of bytecode
+        struct {                              //  bytecode state
+          u3p(u3h_root) har_p;                //  formula->post of bytecode
         } byc;
 
-        struct {                              //  namespace
+        struct {                              //  scry namespace
           u3_noun gul;                        //  (list $+(* (unit (unit)))) now
         } ski;
 
@@ -175,8 +175,11 @@
           u3_noun day;                        //  doss, only in u3H (moveme)
         } pro;
 
-        struct {                              //  memoization
-          u3p(u3h_root) har_p;                //  (map (pair term noun) noun)
+        struct {                              //  memoization caches
+          u3p(u3h_root) har_p;                //  transient
+          u3p(u3h_root) per_p;                //  persistent
+          u3p(u3h_root) fod_p;                //  ford  NB: not used
+          u3p(u3h_root) sam_p;                //  ames  NB: not used
         } cax;
       } u3a_road;
       typedef u3a_road u3_road;
@@ -232,7 +235,7 @@
     /* u3a_is_atom(): yes if noun [som] is direct atom or indirect atom.
     */
 #     define u3a_is_atom(som)    c3o(u3a_is_cat(som), \
-                                         u3a_is_pug(som))
+                                     u3a_is_pug(som))
 #     define u3ud(som)           u3a_is_atom(som)
 
     /* u3a_is_cell: yes if noun [som] is cell.

pkg/noun/hashtable.h

@@ -16,9 +16,8 @@
     ***  corresponding to the 32-slot nodes for everything under
     ***  the root node.
     ***
-    ***  We store an extra "freshly warm" bit for a simple
-    ***  clock-algorithm reclamation policy, not yet implemented.
-    ***  Search "clock algorithm" to figure it out.
+    ***  We store an extra "freshly warm" bit and use it for a simple
+    ***  clock-algorithm reclamation policy.
     **/
       /* u3h_slot: map slot.
       **

pkg/noun/jets.c

@@ -18,15 +18,6 @@
 #include "vortex.h"
 #include "xtract.h"
 
-/**  Data structures.
-**/
-
-/* _cj_hank: cached hook information.
- */
-typedef struct {
-  u3_weak  hax;                     //  axis of hooked inner core
-  u3j_site sit_u;                   //  call-site data
-} _cj_hank;
 
 /**  Functions.
 **/
@@ -1069,18 +1060,18 @@ _cj_prog(u3_weak loc, u3_noun fol)
 /* cj_hank_find(): find cached hook information, keyed by arbitrary
  *                 prefix and term cords. RETAIN.
  */
-static _cj_hank*
+static u3j_hank*
 _cj_hank_find(u3_noun pre, u3_noun tam)
 {
   u3_noun key = u3nc(u3k(pre), u3k(tam));
   u3_noun got = u3h_git(u3R->jed.han_p, key);
 
   if ( u3_none != got ) {
     u3z(key);
-    return u3to(_cj_hank, got);
+    return u3to(u3j_hank, got);
   }
   else {
-    _cj_hank* new_u = u3a_walloc(c3_wiseof(_cj_hank));
+    u3j_hank* new_u = u3a_walloc(c3_wiseof(u3j_hank));
     u3a_road* rod_u = u3R;
 
     while ( rod_u->par_p && u3_none == got ) {
@@ -1092,7 +1083,7 @@ _cj_hank_find(u3_noun pre, u3_noun tam)
       new_u->hax = u3_none;
     }
     else {
-      _cj_hank* old_u = u3to(_cj_hank, got);
+      u3j_hank* old_u = u3to(u3j_hank, got);
       if ( u3_none != (new_u->hax = old_u->hax) ) {
         //  it's unusual but safe to "take" here, because
         //  u3a_take will no-op on senior nouns (just as u3k would)
@@ -1101,7 +1092,7 @@ _cj_hank_find(u3_noun pre, u3_noun tam)
       }
     }
 
-    u3h_put(u3R->jed.han_p, key, u3of(_cj_hank, new_u));
+    u3h_put(u3R->jed.han_p, key, u3of(u3j_hank, new_u));
     u3z(key);
     return new_u;
   }
@@ -1112,7 +1103,7 @@ _cj_hank_find(u3_noun pre, u3_noun tam)
  *                  core on return if valid. RETAIN.
  */
 static c3_o
-_cj_hank_fine(_cj_hank* han_u, u3_noun cor, u3_noun *inn)
+_cj_hank_fine(u3j_hank* han_u, u3_noun cor, u3_noun *inn)
 {
   u3_noun hax = han_u->hax;
   if ( u3_none == hax ) {
@@ -1134,7 +1125,7 @@ _cj_hank_fine(_cj_hank* han_u, u3_noun cor, u3_noun *inn)
 /* _cj_hank_lose(): release memory maintained in a hook cache.
 */
 static void
-_cj_hank_lose(_cj_hank* han_u)
+_cj_hank_lose(u3j_hank* han_u)
 {
   if ( u3_none != han_u->hax ) {
     u3z(han_u->hax);
@@ -1145,7 +1136,7 @@ _cj_hank_lose(_cj_hank* han_u)
 /* _cj_hank_fill(): slow path, populate han_u.
  */
 static u3_noun
-_cj_hank_fill(_cj_hank* han_u, u3_noun tam, u3_noun cor)
+_cj_hank_fill(u3j_hank* han_u, u3_noun tam, u3_noun cor)
 {
   u3_weak   loc, col;
   u3_noun   got, pat, nam, huc;
@@ -1642,7 +1633,7 @@ u3j_cook(const c3_c* key_c,
          const c3_c* tam_c)
 {
   u3_noun pro, key, tam, inn;
-  _cj_hank* han_u;
+  u3j_hank* han_u;
 
   u3t_on(glu_o);
   key = u3i_string(key_c);
@@ -1992,11 +1983,11 @@ u3j_rite_mine(u3j_rite* rit_u, u3_noun clu, u3_noun cor)
 
 /* _cj_take_hank_cb(): u3h_take_with cb for taking hanks
 */
-static u3p(_cj_hank)
-_cj_take_hank_cb(u3p(_cj_hank) nah_p)
+static u3p(u3j_hank)
+_cj_take_hank_cb(u3p(u3j_hank) nah_p)
 {
-  _cj_hank* nah_u = u3to(_cj_hank, nah_p);
-  _cj_hank* han_u = u3a_walloc(c3_wiseof(_cj_hank));
+  u3j_hank* nah_u = u3to(u3j_hank, nah_p);
+  u3j_hank* han_u = u3a_walloc(c3_wiseof(u3j_hank));
 
   if ( u3_none == nah_u->hax ) {
     han_u->hax = u3_none;
@@ -2007,7 +1998,7 @@ _cj_take_hank_cb(u3p(_cj_hank) nah_p)
     u3j_site_take(&(han_u->sit_u), &(nah_u->sit_u));
   }
 
-  return u3of(_cj_hank, han_u);
+  return u3of(u3j_hank, han_u);
 }
 
 /* u3j_take(): copy junior jet state.
@@ -2029,25 +2020,25 @@ static void
 _cj_merge_hank_cb(u3_noun kev, void* wit)
 {
   u3p(u3h_root) han_p = *(u3p(u3h_root)*)wit;
-  _cj_hank* nah_u;
+  u3j_hank* nah_u;
   u3_noun key;
-  u3p(_cj_hank) nah_p;
+  u3p(u3j_hank) nah_p;
   u3x_cell(kev, &key, &nah_p);
 
-  nah_u = u3to(_cj_hank, nah_p);
+  nah_u = u3to(u3j_hank, nah_p);
 
   if ( u3_none == nah_u->hax ) {
     u3a_wfree(nah_u);
   }
   else {
-    _cj_hank* han_u;
+    u3j_hank* han_u;
     u3_weak     got = u3h_git(u3R->jed.han_p, key);
 
     if ( u3_none == got )  {
       han_u = nah_u;
     }
     else {
-      han_u = u3to(_cj_hank, got);
+      han_u = u3to(u3j_hank, got);
 
       if ( u3_none != han_u->hax ) {
         u3z(han_u->hax);
@@ -2058,7 +2049,7 @@ _cj_merge_hank_cb(u3_noun kev, void* wit)
       u3a_wfree(nah_u);
     }
 
-    u3h_put(han_p, key, u3of(_cj_hank, han_u));
+    u3h_put(han_p, key, u3of(u3j_hank, han_u));
   }
 }
 
@@ -2170,7 +2161,7 @@ _cj_warm_tap(u3_noun kev, void* wit)
 static void
 _cj_ream_hank(u3_noun kev)
 {
-  u3j_site_ream(&(u3to(_cj_hank, u3t(kev))->sit_u));
+  u3j_site_ream(&(u3to(u3j_hank, u3t(kev))->sit_u));
 }
 
 /* u3j_ream(): rebuild warm state
@@ -2304,7 +2295,7 @@ static void
 _cj_mark_hank(u3_noun kev, void* dat)
 {
   c3_w* tot_w = (c3_w*) dat;
-  _cj_hank* han_u = u3to(_cj_hank, u3t(kev));
+  u3j_hank* han_u = u3to(u3j_hank, u3t(kev));
   *tot_w += u3a_mark_ptr(han_u);
   if ( u3_none != han_u->hax ) {
     *tot_w += u3a_mark_noun(han_u->hax);
@@ -2337,12 +2328,12 @@ u3j_mark(FILE* fil_u)
   return u3a_maid(fil_u, "total jet stuff", tot_w);
 }
 
-/* _cj_free_hank(): free an entry from the hank cache.
+/* u3j_free_hank(): free an entry from the hank cache.
 */
-static void
-_cj_free_hank(u3_noun kev)
+void
+u3j_free_hank(u3_noun kev)
 {
-  _cj_hank* han_u = u3to(_cj_hank, u3t(kev));
+  u3j_hank* han_u = u3to(u3j_hank, u3t(kev));
   if ( u3_none != han_u->hax ) {
     u3z(han_u->hax);
     u3j_site_lose(&(han_u->sit_u));
@@ -2355,7 +2346,7 @@ _cj_free_hank(u3_noun kev)
 void
 u3j_free(void)
 {
-  u3h_walk(u3R->jed.han_p, _cj_free_hank);
+  u3h_walk(u3R->jed.han_p, u3j_free_hank);
   u3h_free(u3R->jed.war_p);
   u3h_free(u3R->jed.cod_p);
   u3h_free(u3R->jed.han_p);
@@ -2379,7 +2370,7 @@ u3j_reclaim(void)
   // }
   //  clear the jet hank cache
   //
-  u3h_walk(u3R->jed.han_p, _cj_free_hank);
+  u3h_walk(u3R->jed.han_p, u3j_free_hank);
   u3h_free(u3R->jed.han_p);
   u3R->jed.han_p = u3h_new();
 }

pkg/noun/jets.h

@@ -126,6 +126,13 @@
         u3p(u3j_fink) fin_p;          //  fine check
       } u3j_site;
 
+      /* u3j_hank: cached hook information.
+       */
+      typedef struct {
+        u3_weak  hax;                     //  axis of hooked inner core
+        u3j_site sit_u;                   //  call-site data
+      } u3j_hank;
+
   /** Globals.
   **/
     /* u3_Dash: jet dashboard.
@@ -297,6 +304,11 @@
         void
         u3j_free(void);
 
+      /* u3j_free_hank(): free an entry from the hank cache.
+      */
+        void
+        u3j_free_hank(u3_noun kev);
+
       /* u3j_reclaim(): clear ad-hoc persistent caches to reclaim memory.
       */
         void

pkg/noun/jets/f/ut_crop.c

@@ -20,15 +20,15 @@ u3wfu_crop(u3_noun cor)
     u3_weak vet = u3r_at(u3qfu_van_vet, van);
     c3_m  fun_m = 141 + c3__crop + ((!!vet) << 8);
     u3_noun key = u3z_key_3(fun_m, sut, ref, bat);
-    u3_weak pro = u3z_find(key);
+    u3_weak pro = u3z_find(u3z_memo_toss, key);
 
     if ( u3_none != pro ) {
       u3z(key);
       return pro;
     }
     else {
       pro = u3n_nock_on(u3k(cor), u3k(u3x_at(u3x_bat, cor)));
-      return u3z_save(key, pro);
+      return u3z_save(u3z_memo_toss, key, pro);
     }
   }
 }

pkg/noun/jets/f/ut_fish.c

@@ -21,15 +21,15 @@ u3wfu_fish(u3_noun cor)
     u3_weak vet = u3r_at(u3qfu_van_vet, van);
     c3_m  fun_m = 141 + c3__fish + ((!!vet) << 8);
     u3_noun key = u3z_key_3(fun_m, sut, axe, bat);
-    u3_weak pro = u3z_find(key);
+    u3_weak pro = u3z_find(u3z_memo_toss, key);
 
     if ( u3_none != pro ) {
       u3z(key);
       return pro;
     }
     else {
       pro = u3n_nock_on(u3k(cor), u3k(u3x_at(u3x_bat, cor)));
-      return u3z_save(key, pro);
+      return u3z_save(u3z_memo_toss, key, pro);
     }
   }
 }

pkg/noun/jets/f/ut_fuse.c

@@ -20,15 +20,15 @@ u3wfu_fuse(u3_noun cor)
     u3_weak vet = u3r_at(u3qfu_van_vet, van);
     c3_m  fun_m = 141 + c3__fuse + ((!!vet) << 8);
     u3_noun key = u3z_key_3(fun_m, sut, ref, bat);
-    u3_weak pro = u3z_find(key);
+    u3_weak pro = u3z_find(u3z_memo_toss, key);
 
     if ( u3_none != pro ) {
       u3z(key);
       return pro;
     }
     else {
       pro = u3n_nock_on(u3k(cor), u3k(u3x_at(u3x_bat, cor)));
-      return u3z_save(key, pro);
+      return u3z_save(u3z_memo_toss, key, pro);
     }
   }
 }

pkg/noun/jets/f/ut_mint.c

@@ -22,15 +22,15 @@ u3wfu_mint(u3_noun cor)
     c3_m  fun_m = 141 + c3__mint;
     u3_noun vet = u3r_at(u3qfu_van_vet, van);
     u3_noun key = u3z_key_5(fun_m, vet, sut, gol, gen, bat);
-    u3_weak pro = u3z_find(key);
+    u3_weak pro = u3z_find(u3z_memo_toss, key);
 
     if ( u3_none != pro ) {
       u3z(key);
       return pro;
     }
     else {
       pro = u3n_nock_on(u3k(cor), u3k(u3x_at(u3x_bat, cor)));
-      return u3z_save(key, pro);
+      return u3z_save(u3z_memo_toss, key, pro);
     }
   }
 }