@@ -5,10 +5,10 @@ template = "doc.html"
5aliases = ["/docs/learn/hoon/hoon-tutorial/gall/"]
5aliases = ["/docs/learn/hoon/hoon-tutorial/gall/"]
8−> Note: This guide is outdated. For an updated explanation of Gall, take a look at [/tutorial/arvo/gall](/docs/tutorials/arvo/gall)
10Gall is the Arvo vane responsible for handling user space applications. When writing a Gall application there are several things you will need to understand.
8Gall is the Arvo vane responsible for handling user space applications. When writing a Gall application there are several things you will need to understand.
10+For another explanation of Gall, take a look at [/tutorial/arvo/gall](/docs/tutorials/arvo/gall)
12## bowl and moves
12## bowl and moves
14The [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.
14The [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
35Gall applications can have a number of arms that get called depending on the information they are sent.
35Gall applications can have a number of arms that get called depending on the information they are sent.
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.
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
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.
43−```hoon
46+### +on-load
45− |= a=(unit *)
48+This arm is called immediately after the agent is upgraded. It receives
46− `(quip move _+>.$)`[~ +>.$]
49+a `vase` of the state of the previously-running version of the agent,
47−```
50+which allows it to cleanly upgrade from the old agent.
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`.
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
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`.
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
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.
57−`++coup` is a response handler for any pokes our application sent out.
84+### +on-peek
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.
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`.
63−### ++pull
96+### +on-agent
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:
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`.
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
71−### ++reap
110+- `%fact`: update from the publisher.
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.
75−### ++diff
114+### +on-arvo
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`).
79−### ++sigh
120+### +on-fail
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.
83−Let's take a look in the next section at an example Gall app.