@@ -5,14 +5,15 @@ template = "doc.html"
7This section will be reference documentation for the data types used by our
7This section will be reference documentation for the data types used by our
8−filesystem. Parts of it may be inaccurate as of March 2021. As a general guide,
8+filesystem. It is up to date as of March 2021.
9−we recommend reading and attempting to understand the data structures used in
10+As a general guide, we recommend reading and attempting to understand the data
10−any Hoon code before you try to read the code itself. Although complete
11+structures used in any Hoon code before you try to read the code itself.
11−understanding of the data structures is impossible without seeing them used in
12+Although complete understanding of the data structures is impossible without
12−the code, an 80% understanding greatly clarifies the code. As another general
13+seeing them used in the code, an 80% understanding greatly clarifies the code.
13−guide, when reading Hoon, it rarely pays off to understand every line of code
14+As another general guide, when reading Hoon, it rarely pays off to understand
14−when it appears. Try to get the gist of it, and then move on. The next time you
15+every line of code when it appears. Try to get the gist of it, and then move on.
15−come back to it, it'll likely make a lot more sense.
16+The next time you come back to it, it'll likely make a lot more sense.
17### Data Models
18### Data Models
@@ -23,11 +24,11 @@ at least skimming, this so that you get a rough idea of how our state is
25The types that are certainly worth reading are `++raft`, `++room`,
26The types that are certainly worth reading are `++raft`, `++room`,
26−`++dome:clay`, `++ankh:clay`, `++rung:clay`, `++rang:clay`, `++blob:clay`, `++yaki:clay`, and `++nori:clay`
27+`++dome:clay`, `++ankh:clay`, `++rung:clay`, `++rang:clay`, `++blob:clay`,
27−(possibly in that order). All in all, though, this section isn't too
28+`++yaki:clay`, and `++nori:clay` (possibly in that order). All in all, though,
28−long, so many readers may wish to quickly read through all of it. If you
29+this section isn't too long, so many readers may wish to quickly read through
29−get bored, though, just skip to the next section. You can always come
30+all of it. If you get bored, though, just skip to the next section. You can
30−back when you need to.
31+always come back when you need to.
32### `++raft`, formal state
33### `++raft`, formal state
@@ -38,20 +39,43 @@ back when you need to.
38 ran=rang :: hashes
39 ran=rang :: hashes
44+ $: rom=room :: domestic
45+ hoy=(map ship rung) :: foreign
47+ mon=(map term beam) :: mount points
48+ hez=(unit duct) :: sync duct
49+ cez=(map @ta crew) :: permission groups
50+ pud=(unit [=desk =yoki]) :: pending update
42−This is the state of our vane. Anything that must be remembered between
54+This is the state of the vane. Anything that must be remembered between
43−calls to clay is stored in this state.
55+calls to Clay is stored in this state.
45−`fat` is the set of domestic servers. This stores all the information
46−that is specfic to a particular ship on this pier. The keys to this map
47−are the ships on the current pier. all the information that is specific
48−to a particular foreign ship. The keys to this map are all the ships
49−whose filesystems we have attempted to access through clay.
51`ran` is the store of all commits and deltas, keyed by hash. The is
57`ran` is the store of all commits and deltas, keyed by hash. The is
52where all the "real" data we know is stored; the rest is "just
58where all the "real" data we know is stored; the rest is "just
53bookkeeping".
59bookkeeping".
61+`rom` is our domestic state. It consists of a `duct` to
62+[Dill](@/docs/arvo/dill/dill.md) and a collection of `desk`s.
64+`hoy` is a collection of foreign ships for which we know something about their
67+`ran` is the object store. It has maps of commit hashes to commits and content
70+`mon` is a collection of Unix mount points. `term` is the mount point (relative
71+to th pier) and `beam` is a domestic Clay directory.
73+`hez` is the Unix duct that `%ergo` `%gift`s should be sent to.
75+`cez` is a collection of named permission groups.
77+`pud` is an update that's waiting on a kernel upgrade.
55#### `++room`, filesystem per domestic ship
79#### `++room`, filesystem per domestic ship
@@ -161,10 +185,10 @@ represents the data at the node referenced by the path at case `p`, if
161we've gotten to that case (else null). We only send a notification along
185we've gotten to that case (else null). We only send a notification along
162the subscription if the data at a new revision is different than it was.
186the subscription if the data at a new revision is different than it was.
164−### `++care:clay`, clay submode
188+### `++care:clay`, Clay submode
167− ++ care ?(%u %v %w %x %y %z) :: clay submode
191+ ++ care ?(%u %v %w %x %y %z) :: Clay submode
170This specifies what type of information is requested in a subscription
194This specifies what type of information is requested in a subscription
@@ -547,7 +571,7 @@ is not a complicated type; it is not difficult to work out the meaning.
550−This describes a change that we are asking clay to make to the desk.
574+This describes a change that we are asking Clay to make to the desk.
551There are two kinds of changes that may be made: we can modify files or
575There are two kinds of changes that may be made: we can modify files or
552we can apply a label to a commit.
576we can apply a label to a commit.
@@ -604,7 +628,7 @@ commits or data need be here.
605This represents a request for data about a particular desk. If `q`
629This represents a request for data about a particular desk. If `q`
606contains a `rave`, then this opens a subscription to the desk for that
630contains a `rave`, then this opens a subscription to the desk for that
607−data. If `q` is null, then this tells clay to cancel the subscription
631+data. If `q` is null, then this tells Clay to cancel the subscription
608along this duct.
632along this duct.
610#### `++riot:clay`, response
634#### `++riot:clay`, response
@@ -698,7 +722,7 @@ request change. For the format of the requested change, see the
698documentation for `++nori:clay` above.
722documentation for `++nori:clay` above.
700When a file is changed in the unix filesystem, vere will send a `%into`
724When a file is changed in the unix filesystem, vere will send a `%into`
701−kiss. This tells clay that the duct over which the kiss was sent is the
725+kiss. This tells Clay that the duct over which the kiss was sent is the
702duct that unix is listening on for changes. From within Arvo, though, we
726duct that unix is listening on for changes. From within Arvo, though, we
703should never send a `%into` kiss. The `%info` kiss is exactly identical
727should never send a `%into` kiss. The `%info` kiss is exactly identical
704except it does not reset the duct.
728except it does not reset the duct.
@@ -711,7 +735,7 @@ except it does not reset the duct.
712These kisses are currently identical to `%info` and `%into`, though this
736These kisses are currently identical to `%info` and `%into`, though this
713will not always be the case. The intent is for these kisses to allow
737will not always be the case. The intent is for these kisses to allow
714−typed changes to clay so that we may store typed data. This is currently
738+typed changes to Clay so that we may store typed data. This is currently
715unimplemented.
739unimplemented.