git.iko.soy/urbit.org
on c19bc7a help sign in
urbit.org/docs/tutorials/internals/gall.udon
132 lines 4.3 kB history raw
1:- :~ navhome/'/docs/'
2 navuptwo/'true'
3 sort/'7'
4 title/'Gall'
5 ==
6;>
8# Gall
10Our application server manager.
12It allows applications and vanes to send messages to applications and
13subscribe to data streams. This requires `%gall` to be a sort of a
14hypervisor. Messages coming into `%gall` are routed to the intended
15application, and the response comes back along the same route. If the
16intended target is on another ship, `%gall` will behind-the-scenes route
17it through ames to the other ship to run. This provides an abstraction
18where all apps on all ships are communicated with over the same
19interface.
21`%gall` neither accepts events from unix nor produces effects. It exists
22entirely for the benefit of other vanes and, in particular,
23applications. Eyre exposes `%gall`'s interface over http, and ames does
24the same over the ames network. `%gall` uses ford to compile and run the
25applications.
27# Cards
29`%gall` accepts the following cards. The first three are the most
30commonly used, while the others are primarily used internally.
32### `%mess`
34Sends a message to an app. This will result in a call to the app's
35`++poke` arm. The response is exactly one of a `%nice` if the action
36succeeded or a `%mean` if not.
38### `%show`
40Subscribes to a stream from an app. This will result in a call to the
41app's either `++peek` or `++peer` arm. The first response will always be
42either a `%nice` or a `%mean`, indicating whether or not the
43subscription was successful. After the first response, there will be
44zero or more responses of either `%rush` or `%rust`, which communicate
45either a differential or full update to the data stream. There may be a
46`%mean`, which indicates that the subscription has been canceled and no
47more responses will be received along this stream.
50### `%nuke`
52Unsubscribes the current duct from its stream. This receives a response
53of either a `%nice` or a `%mean`. Note that a response of `%nice` does
54not imply that the current duct was in fact subscribed to any stream.
56### `%init`
58Initializes a ship's apps. This should be called exactly once for each
59ship on the pier. This produces no moves in response.
61### `%sire`
63Instantiates a child app. The app will be at path `[p parent-path]`, and
64it will be an instance of the `q` app. The only response will be `%gone`
65when the child dies.
68### `%rote`
70Signifies a remote request from ames. `r` should be of type `rook`. This
71how an app on a foreign ship may send a `%mess`, `%show`, or `%nuke`
72card. Note that `%gall` automatically converts `%mess`, `%show`, and
73`%nuke` into ames messages behind the scenes, so the only entity that
74should use `%rote` and `%roth` is ames. Formally, the response is either
75a `%nice` or a `%mean`, which ames uses to give a positive or negative
76ack. A logical response comes by passing a `%roth` card.
79### `%roth`
81Gives the response received from a remote request. `r` should be of type
82`roon`. This is how an app responds to a foreign request with a `%rush`,
83`%rust`, `%nice`, or `%mean`. The response is either a `%nice` or a
84`%mean`. Even though we, as the proverb goes, "never ack an ack", we do
85need to acknowledge these responses since they're really independent
86one-way messages.
89### `%wipe`
91Wipes the given app from memory. This is generally considered a hack,
92but it is sometimes useful during development to wipe the state of an
93app. We don't guarantee that this actually completely wipes the app.
94Generally, you want to use a `%cide` card if you actually want to kill
95an app. This gives no response.
98### `%cide`
100Kills an app and all its children. Even though it's not technically a
101part of `%gall`'s interface since it's not in `++kiss` and can't be
102called from the outside, it's worth mentioning `%cide`, which may be
103called from within `%gall` apps. It should call `++part` to allow the
104app any last words. This gives no response.
106Service Gates
107-------------
109### `++poke`
111Handles incoming messages. Most commonly with an associated `%logo`. For
112example `++poke-json` handles an incoming JSON request from `%eyre`.
114### `++peer`
116Handles incoming subscriptions.
118### `++pull`
120Handles dropping subscribers.
122### `++pour`
124Handles responses to `%pass` moves.
126### `++park`
128Save state on update.
130### `++prep`
132Load state on update.