@@ -5,10 +5,10 @@ template = "doc.html"
55aliases = ["/docs/learn/hoon/hoon-tutorial/gall/"]
66+++
77
8−> Note: This guide is outdated. For an updated explanation of Gall, take a look at [/tutorial/arvo/gall](/docs/tutorials/arvo/gall)
9−
108Gall is the Arvo vane responsible for handling user space applications. When writing a Gall application there are several things you will need to understand.
119
10+For another explanation of Gall, take a look at [/tutorial/arvo/gall](/docs/tutorials/arvo/gall)
11+
1212## bowl and moves
1313
1414The [core](/docs/glossary/core/) of a gall app is a [door](/docs/glossary/door/) which has two parts of its subject, the first a `bowl:gall` which contains a lot of standard things used by gall apps, the second a type containing app state information.
@@ -34,50 +34,94 @@ Each `card` is a pair of a tag and a [noun](/docs/glossary/noun/). The tag indic
3434
3535Gall applications can have a number of arms that get called depending on the information they are sent.
3636
37−### ++prep
37+This arm is called once when the agent is started. It has no input and
38+lets you perform any initial IO.
3839
39−`++prep` is the arm that is called when an application is first started or when it's updated. This arm should be a [gate](/docs/glossary/gate/) that takes a `unit` of a noun and provides a way, if necessary, to make any changes to the application's data required by an upgrade. As a reminder, a `unit` is a type that may contain another type or it might contain `~`. They are used when there may or may not be some data available.
40+### +on-save
4041
41−Often when developing an application you will not initially care about the data. Here is a sample `++prep` arm that will simply throw away the previous application state.
42+This arm is called immediately before the agent is upgraded. It
43+packages the permament state of the agent in a `vase` for the next version
44+of the agent. Unlike most handlers, this cannot produce effects.
4245
43−```hoon
44−++ prep
45− |= a=(unit *)
46− `(quip move _+>.$)`[~ +>.$]
47−```
46+### +on-load
47+
48+This arm is called immediately after the agent is upgraded. It receives
49+a `vase` of the state of the previously-running version of the agent,
50+which allows it to cleanly upgrade from the old agent.
51+
52+### +on-poke
53+
54+This arm is called when the agent is "poked". The input is a `cage`, so
55+it's a pair of a mark and a dynamic `vase`.
56+
57+### +on-watch
4858
49−### ++poke
59+This arm is called when a program wants to subscribe to the agent on a
60+particular `path`. The agent may or may not need to perform setup steps
61+to intialize the subscription. It may produce a `%give`
62+`%subscription-result` to the subscriber to get it up to date, but after
63+this event is complete, it cannot give further updates to a specific
64+subscriber. It must give all further updates to all subscribers on a
65+specific `path`.
5066
51−`++poke` is one of the primary arms used when building a Gall application. A `poke` is often a request to perform some operation that the application was designed for. These are requests from outside the application. `++poke` will get called with the raw noun data which can then be inspected to perform the requested actions with.
67+If this arm crashes, then the subscription is immediately terminated.
68+More specifcally, it never started -- the subscriber will receive a
69+negative `%watch-ack`. You may also produce an explicit `%kick` to
70+close the subscription without crashing -- for example, you could
71+produce a single update followed by a `%kick`.
5272
53−Many arms, `++poke` included, have variants that end in the name of a mark e.g. `++poke-noun`. Which one gets called will be based on which mark was used to create the poke. Gall will attempt to use the most specific arm it can find, eventually falling back to `++poke` if no matching mark arm is found. Use of these mark arms, however, is now discouraged.
73+### +on-leave
5474
55−### ++coup
75+This arm is called when a program becomes unsubscribed to you.
76+Subscriptions may close because the subscriber intentionally
77+unsubscribed, but they also could be closed by an intermediary. For
78+example, if a subscription is from another ship which is currently
79+unreachable, Ames may choose to close the subscription to avoid queueing
80+updates indefinitely. If the program crashes while processing an
81+update, this may also generate an unsubscription. You should consider
82+subscriptions to be closable at any time.
5683
57−`++coup` is a response handler for any pokes our application sent out.
84+### +on-peek
5885
59−### ++peer
86+This arm is called when a program reads from the agent's "scry"
87+namespace, which should be referentially transparent. Unlike most
88+handlers, this cannot perform IO, and it cannot change the state. All
89+it can do is produce a piece of data to the caller, or not.
6090
61−`++peer` is used to handle subscriptions. When something subscribes to your application this arm will run. The something could be another Gall application on your ship or another ship or a tile from landscape or anything else that is able to communicate with Gall. Your outgoing subscriptions will not be tracked automatically but incoming ones will live in `sup.bowl` so that you can send information to them when required.
91+If this arm produces `[~ ~ data]`, then `data` is the value at the the
92+given `path`. If it produces `[~ ~]`, then there is no data at the given
93+`path` and never will be. If it produces `~`, then we don't know yet
94+whether there is or will be data at the given `path`.
6295
63−### ++pull
96+### +on-agent
6497
65−`++pull` is run when someone unsubscribes from your application, this is used to run any changes needed for your application when they unsubscribed. Their removal from `sup.bowl` is handled for you.
98+This arm is called to handle responses to `%give` moves to other agents.
99+It will be one of the following types of response:
66100
67−### ++quit
101+- `%poke-ack`: acknowledgment (positive or negative) of a poke. If the
102+ value is `~`, then the poke succeeded. If the value is `[~ tang]`,
103+ then the poke failed, and a printable explanation (e.g. a stack trace)
104+ is given in the `tang`.
68105
69−`++quit` gets called when a subscription is dropped. Often you will just want to resubscribe when this happens.
106+- `%watch-ack`: acknowledgment (positive or negative) of a subscription.
107+ If negative, the subscription is already ended (technically, it never
108+ started).
70109
71−### ++reap
110+- `%fact`: update from the publisher.
72111
73−`++reap` is to `++peer` as `++coup` is to `++poke`, that is to say it's the arm that gets run in acknowledgment of outgoing subscription requests.
112+- `%kick`: notification that the subscription has ended.
74113
75−### ++diff
114+### +on-arvo
76115
77−`++diff` gets called when an application you are subscribed to has an update. It could either be an entirely new set of data for that application or an update to existing data.
116+This arm is called to handle responses to `%pass` `move`s to vanes. The
117+list of possible responses from the system is statically defined in
118+sys/zuse.hoon (grep for `+ sign-arvo`).
78119
79−### ++sigh
120+### +on-fail
80121
81−`++sigh` gets called when Eyre has a response to an http request made by our application.
122+If an error happens in `+on-poke`, the crash report goes into the
123+`%poke-ack` response. Similarly, if an error happens in
124+`+on-subscription`, the crash report goes into the `%watch-ack`
125+response. If a crash happens in any of the other handlers, the report
126+is passed into this arm.
82127
83−Let's take a look in the next section at an example Gall app.