@@ -1,9 +1,9 @@
2# The new Gall model
2# The new Gall model
4−This document is complemented by the source code of applications that use the new gall model (like hall), but doesn't require it. Code snippets and diagrams will be provided where useful. Some knowledge of Hoon and the functioning of Hoon apps is assumed.
4+This document is complemented by the source code of applications that use the new Gall model (like hall), but doesn't require it. Code snippets and diagrams will be provided where useful. Some knowledge of Hoon and the functioning of Hoon apps is assumed.
6−New gall has not yet fully solidified. As such, structure and naming are tentative to change.
6+New Gall has not yet fully solidified. As such, structure and naming are tentative to change.
8## Table of contents
8## Table of contents
@@ -11,7 +11,7 @@ New gall has not yet fully solidified. As such, structure and naming are tentati
12## Renewing a pillar of Arvo
12## Renewing a pillar of Arvo
14−When you write an app, gall is responsible for making sure its event arms like `++poke` get called when they need to. In essence, it provides developers with a consistent interface for hooking their app up to the operating system.
14+When you write an app, Gall is responsible for making sure its event arms like `++poke` get called when they need to. In essence, it provides developers with a consistent interface for hooking their app up to the operating system.
15It's not doing a lot to make sure this is done in a structured way though, which results in apps (especially larger ones) feeling like big tangled messes. Something needs to be done about this.
15It's not doing a lot to make sure this is done in a structured way though, which results in apps (especially larger ones) feeling like big tangled messes. Something needs to be done about this.
17### Problems
17### Problems
@@ -33,23 +33,23 @@ cost is extremely welcome.
34### Solutions
34### Solutions
36−Let's imagine a world in which gall *does* help, in both those places.
36+Let's imagine a world in which Gall *does* help, in both those places.
38−It would be wonderful if gall could take care of all standard subscription management logic for you, and direct the flow of code as it concludes is appropriate.
38+It would be wonderful if Gall could take care of all standard subscription management logic for you, and direct the flow of code as it concludes is appropriate.
39−Applications, then, would have to help gall by providing the different parts of this flow, and the checks that allow gall to make the right decisions. This takes some work out of the developer's hands and results in more structured application code.
39+Applications, then, would have to help Gall by providing the different parts of this flow, and the checks that allow Gall to make the right decisions. This takes some work out of the developer's hands and results in more structured application code.
41−If we expand on that a bit we can even have gall help us in untangling state changes from side effects. We do so by separating state changes into two phases: *analyzing* what changes need to be made, and *applying* those changes.
41+If we expand on that a bit we can even have Gall help us in untangling state changes from side effects. We do so by separating state changes into two phases: *analyzing* what changes need to be made, and *applying* those changes.
42−But where do the side-effects go then? We need to realize there's two kinds: side-effects that are subscription updates, and those that aren't. The latter get produces by applying state changes, while the former get integrated into the gall flow we described above.
42+But where do the side-effects go then? We need to realize there's two kinds: side-effects that are subscription updates, and those that aren't. The latter get produces by applying state changes, while the former get integrated into the Gall flow we described above.
43−Since subscriptions are essentially queries to an app, requesting a specific part of its data/state, we can deduce subscription updates from state changes. We merely provide the logic, and gall chains it all together.
43+Since subscriptions are essentially queries to an app, requesting a specific part of its data/state, we can deduce subscription updates from state changes. We merely provide the logic, and Gall chains it all together.
45−Having gall support all this allows us to cleanly and structurally untangle state change analysis, application, and subscription logic into their own arms.
45+Having Gall support all this allows us to cleanly and structurally untangle state change analysis, application, and subscription logic into their own arms.
46For trivial apps, this might result in some arms with trivial code. Though it may feel like writing cruft, it makes understanding the app just as simple as it actually as.
46For trivial apps, this might result in some arms with trivial code. Though it may feel like writing cruft, it makes understanding the app just as simple as it actually as.
47For more complex apps, all logic is no longer a big chunk of "what do we do when x happens?", but rather a couple of smaller chunks, like "x happened, how does that change our state?" and "if our state changes like y, what does that mean for subscription z?" These are precisely the kinds of questions that application developers should be asked.
47For more complex apps, all logic is no longer a big chunk of "what do we do when x happens?", but rather a couple of smaller chunks, like "x happened, how does that change our state?" and "if our state changes like y, what does that mean for subscription z?" These are precisely the kinds of questions that application developers should be asked.
50−## As seen in new gall
50+## As seen in new Gall
52−Of course for the above to be made into reality, gall will need to see some changes. Let's outline the new structures and the arms they get passed between.
52+Of course for the above to be made into reality, Gall will need to see some changes. Let's outline the new structures and the arms they get passed between.
54### Structures
54### Structures
@@ -79,12 +79,12 @@ This also wouldn't be Urbit if we couldn't boil that down to a few simple pseudo
79 (gain rumor:(feel query delta) prize:(peek brain query))
79 (gain rumor:(feel query delta) prize:(peek brain query))
82−There, in the first three arms we already have the bulk of new gall! `++gain` won't be part of it, since most applications don't need to keep track of `prize`s directly. Those that do may still implement and hook it up themselves though.
82+There, in the first three arms we already have the bulk of new Gall! `++gain` won't be part of it, since most applications don't need to keep track of `prize`s directly. Those that do may still implement and hook it up themselves though.
84−Of course, these aren't all of the new gall arms. Most important to still mention is `++leak`, which takes a `ship` and `query` and checks if the former has permission to ask for the latter.
84+Of course, these aren't all of the new Gall arms. Most important to still mention is `++leak`, which takes a `ship` and `query` and checks if the former has permission to ask for the latter.
85There's also `++look` for asynchronous reads, `++hear` for subscription updates (rumors), `++fail` for dealing with process errors, `++cope` for dealing with transaction results, and `++pour` for dealing with responses from arvo.
85There's also `++look` for asynchronous reads, `++hear` for subscription updates (rumors), `++fail` for dealing with process errors, `++cope` for dealing with transaction results, and `++pour` for dealing with responses from arvo.
86`++prep`, `++poke` and `++pull` continue to function as they do right now.
86`++prep`, `++poke` and `++pull` continue to function as they do right now.
87−For a more verbose specification of all of these, see the new gall spec.
87+For a more verbose specification of all of these, see the new Gall spec.
90## By example
90## By example
@@ -213,22 +213,22 @@ As we saw earlier, for `/number` queries the `delta`s match one-on-one with the
214## Criticism
214## Criticism
216−* Where event arms currently get passed a `wire`, and the new gall described above passes them a custom `query` structure, the original new gall spec gave them `(list coin)`, a "pre-parsed wire". These structures (eg `[%$ p=[p=~.ud q=123]]`) are uncomfortable to work with. Even with a "coin list parsing library" it still doesn't feel ideal.
216+* Where event arms currently get passed a `wire`, and the new Gall described above passes them a custom `query` structure, the original new Gall spec gave them `(list coin)`, a "pre-parsed wire". These structures (eg `[%$ p=[p=~.ud q=123]]`) are uncomfortable to work with. Even with a "coin list parsing library" it still doesn't feel ideal.
217Because of custom structures being easier to work with than lists of knots or coins, writing a `++path-to-query` arm by hand is a small cost for huge gains.
217Because of custom structures being easier to work with than lists of knots or coins, writing a `++path-to-query` arm by hand is a small cost for huge gains.
219* Why do `prize` units mean what they do? Would have expected `~` to mean "invalid" and `[~ ~]` to mean "unavailable" as opposed to the other way around.
219* Why do `prize` units mean what they do? Would have expected `~` to mean "invalid" and `[~ ~]` to mean "unavailable" as opposed to the other way around.
221−* The original new gall spec mentions output lists (like `(list delta)` etc.) to be in reverse order. This was done because adding to the head of a list (`[item list]`) is easier than appending to the tail of a list (`(weld list [item ~])` or other).
221+* The original new Gall spec mentions output lists (like `(list delta)` etc.) to be in reverse order. This was done because adding to the head of a list (`[item list]`) is easier than appending to the tail of a list (`(weld list [item ~])` or other).
222While it's technically easier to produce a list in reverse order, semantically it's yet another thing to keep in mind. Luckily, most of the "add to x, produce all of it later" code is set-and-forget, so probably not a huge deal, but do we really fear a few stray `++flop`s that much?
222While it's technically easier to produce a list in reverse order, semantically it's yet another thing to keep in mind. Luckily, most of the "add to x, produce all of it later" code is set-and-forget, so probably not a huge deal, but do we really fear a few stray `++flop`s that much?
224−* There's some weirdness with relation to relying on old state in `++feel` to determine whether a query result actually changed. Just relying on state in general for delta-to-rumor conversion may or may not violate the new gall spec.
224+* There's some weirdness with relation to relying on old state in `++feel` to determine whether a query result actually changed. Just relying on state in general for delta-to-rumor conversion may or may not violate the new Gall spec.
226−* The original new gall spec specifies `++leak` as taking a `(unit (set ship))`, where `~` means public. Is there a use case for checking more than just a single ship?
226+* The original new Gall spec specifies `++leak` as taking a `(unit (set ship))`, where `~` means public. Is there a use case for checking more than just a single ship?
228* Gall should probably cache `++feel` results during a single pass, to avoid the cycles of generating what it can be certain of is the same `(unit rumor)`. (But then for eg `/circle/nom/13` and `/circle/nom/14` it would still recalculate. Better than nothing.)
228* Gall should probably cache `++feel` results during a single pass, to avoid the cycles of generating what it can be certain of is the same `(unit rumor)`. (But then for eg `/circle/nom/13` and `/circle/nom/14` it would still recalculate. Better than nothing.)
231## Further reading
231## Further reading
233−@TODO original gall-spec.hoon / heed.hoon
233+[Original new gall spec by ~sorreg-namtyv](gall-spec_orig.hoon)
234−@TODO proposed gall-spec.hoon / heed.hoon
234+@TODO proposed gall-spec.hoon