@@ -0,0 +1,78 @@
1++++
2+title = "Gall"
3+weight = 0
4+template = "doc.html"
5++++
6+
7+Gall is the Arvo vane responsible for handling user space applications. When writing a Gall application there are several thinks you will need to understand.
8+
9+## bowl and moves
10+
11+The core of a gall app is a door which has two parts of it's 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.
12+
13+Vanes in Arvo communicate by means of `moves`. When a move is produced by an arm in a gall app, it's dispatched by Arvo to the correct handler for the request, be it another application or another vane. A `move` is pair of `bone` and `card`. These are essential components to understand when learning to use gall.
14+
15+A `bone` is an opaque cause that initiates a request. When constructing a `move` you can often use `ost.bowl` and when responding an incoming `move` you can use the `bone` in that `move` to construct your response.
16+
17+A `card` is the effect or event that is being requested. Each application should define the set of `cards` it can produce. Here is an excerpt from `clock.hoon` showing it's `cards`
18+
19+```
20++$ card
21+ $% [%poke wire dock poke]
22+ [%http-response =http-event:http]
23+ [%connect wire binding:eyre term]
24+ [%diff %json json]
25+ ==
26+```
27+
28+Each `card` is a pair of a tag and a noun. The tag indicates what the event being triggered is and the noun is any data required for that event.
29+
30+## Arms
31+
32+Gall applications can have a number of arms that get called depending on the information they are sent.
33+
34+### ++prep
35+
36+`++prep` is the arm that is called when an application is first started or when it's updated. This arm should be a 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. 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.
37+
38+```
39+++ prep
40+ |= a=(unit *)
41+ `(quip move _+>.$)`[~ +>.$]
42+```
43+
44+### ++poke
45+
46+`++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.
47+
48+Many arms `++poke` included, have variants that end in the name of a mark e.g. `++poke-noun`. Which one gets called will be base on what 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.
49+
50+### ++coup
51+
52+`++coup` is a response handler for any pokes our application sent out.
53+
54+### ++peer
55+
56+`++peer` is used to handle subscriptions. When something subscribes to your application this arm will run. 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.
57+
58+### ++pull
59+
60+`++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.
61+
62+### ++quit
63+
64+`++quit` gets called when a subscription is dropped. Often you will just want to resubscribe when this happens.
65+
66+### ++reap
67+
68+`++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.
69+
70+### ++diff
71+
72+`++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.
73+
74+### ++sigh
75+
76+`++sigh` gets called when eyre has a response to an http request made by our application.
77+
78+Let's take a look in the next section at an example Gall app.