git.iko.soy/urbit.org
on 514b5fc help sign in
urbit.org/content/docs/arvo/tutorials/move-trace.md
378 lines 17 kB history raw
1+++
2title = "Move Trace"
3weight = 12
4template = "doc.html"
5+++
7In this tutorial we will run a simple "move trace" and use the output to get a
8picture of what the Arvo kernel proper does during the routine task of setting a
9timer. Some level of familiarity with the kernel is required for this section,
10which can be obtained in our [Arvo kernel tutorial](/docs/arvo/overview#the-kernel).
12## Running a move trace
14Ultimately, everything that happens in Arvo is reduced to Unix events, and the
15Arvo kernel acts as a sort of traffic cop for vanes and apps to talk to one
16another. Here we look at how a simple command, `-time ~s1`, goes from pressing
17Enter on your keyboard in Dojo towards returning a notification that one second
18has elapsed.
20To follow along yourself, boot up a fake `~zod` and enter `|verb` into the dojo
21and press Enter to enable verbose mode (this is tracked by the laconic bit
22introduced in the section on [the
23state](/docs/arvo/overview#the-state)) in the kernel documentation, followed by `-time ~s1`
24followed by Enter. Your terminal should pretty print a series of `move`s that looks something like this:
26```
27["" %unix p=%belt //term/1 ~2020.1.14..19.01.25..7556]
28["|" %pass [%d %g] [[%deal [~zod ~zod] %hood %poke] /] [i=//term/1 t=~]]
29["||" %pass [%g %g] [[%deal [~zod ~zod] %dojo %poke] /use/hood/~zod/out/~zod/dojo/drum/phat/~zod/dojo] [i=/d t=~[//term/1]]]
30["|||" %give %g [%unto %fact] [i=/g/use/hood/~zod/out/~zod/dojo/drum/phat/~zod/dojo t=~[/d //term/1]]]
31["||||" %give %g [%unto %fact] [i=/d t=~[//term/1]]]
32["|||||" %give %d %blit [i=//term/1 t=~]]
33["|||" %pass [%g %f] [%build /use/dojo/~zod/drum/hand] [i=/d t=~[//term/1]]]
34["||||" %give %f %made [i=/g/use/dojo/~zod/drum/hand t=~[/d //term/1]]]
35["|||||" %pass [%g %g] [[%deal [~zod ~zod] %spider %watch] /use/dojo/~zod/out/~zod/spider/drum/wool] [i=/d t=~[//term/1]]]
36["||||||" %give %g [%unto %watch-ack] [i=/g/use/dojo/~zod/out/~zod/spider/drum/wool t=~[/d //term/1]]]
37["|||||" %pass [%g %g] [[%deal [~zod ~zod] %spider %poke] /use/dojo/~zod/out/~zod/spider/drum/wool] [i=/d t=~[//term/1]]]
38//term/1]]]
39["||||||" %pass [%g %f] [%build /use/spider/~zod/find/~.dojo_0v6.210tt.1sme1.ev3qm.qgv2e.a754u] [i=/d t=~[//term/1]]]
40["|||||||" %give %f %made [i=/g/use/spider/~zod/find/~.dojo_0v6.210tt.1sme1.ev3qm.qgv2e.a754u t=~[/d //term/1]]]
41["||||||||" %pass [%g %f] [%build /use/spider/~zod/build/~.dojo_0v6.210tt.1sme1.ev3qm.qgv2e.a754u] [i=/d t=~[//term/1]]]
42["|||||||||" %give %f %made [i=/g/use/spider/~zod/build/~.dojo_0v6.210tt.1sme1.ev3qm.qgv2e.a754u t=~[/d //term/1]]]
43["||||||||||" %pass [%g %b] [%wait /use/spider/~zod/thread/~.dojo_0v6.210tt.1sme1.ev3qm.qgv2e.a754u/wait/~2020.1.14..19.01.26..7556] [i=/d t=~[//term/1]]]
44["|||||||||||" %give %b %doze [i=//behn/0v1p.sn2s7 t=~]]
45> -time ~s1
46```
47followed by a pause of one second, then
48```
49["" %unix p=%wake //behn ~2020.1.14..19.01.26..755d]
50["|" %give %b %doze [i=//behn/0v1p.sn2s7 t=~]]
51["|" %give %b %wake [i=/g/use/spider/~zod/thread/~.dojo_0v6.210tt.1sme1.ev3qm.qgv2e.a754u/wait/~2020.1.14..19.01.26..7556 t=~[/d //term/1]]]
52["||" %give %g [%unto %fact] [i=/g/use/dojo/~zod/out/~zod/spider/drum/wool t=~[/d //term/1]]]
53["|||" %give %g [%unto %fact] [i=/g/use/hood/~zod/out/~zod/dojo/drum/phat/~zod/dojo t=~[/d //term/1]]]
54["||||" %give %g [%unto %fact] [i=/d t=~[//term/1]]]
55["|||||" %give %d %blit [i=//term/1 t=~]]
56["||" %give %g [%unto %kick] [i=/g/use/dojo/~zod/out/~zod/spider/drum/wool t=~[/d //term/1]]]
57~s1..0007
58```
59This gives us a move trace that is a list of `move`s and some
60associated metadata. Some of the `move`s are a bit of a distraction from what's
61going on overall such as acknowledgements that a `poke` was received
62(`%poke-ack`s), so we've omitted them for clarity. Furthermore, two `move`s (the
63`%blit` `card`s) is not printed even in verbose mode because it occurs so
64frequently, but there are only two of them here and so we have added it in.
66The main process that is occurring here is a sequence of `%pass` `move`s initiated
67by pressing Enter in the terminal that goes on to be handled by Dill, then Gall,
68and finally Behn. After the timer has elapsed, a sequence of `%give` `move`s is
69begun by Behn, which then passes through Gall and ultimately ends up back at the
70terminal. Any `move`s besides `%pass` in the first segment of the move trace is a
71secondary process utilized for book-keeping, spawning processes, interpreting
72commands, etc. All of this will be explained in detail below.
75It is important to note that this move trace should be thought of
76as being from the "point of view" of the kernel - each line represents the
77kernel taking in a message from one source and passing it along to its
78destination. It is then processed at that destination (which could be a vane or
79an app), and the return of that process is sent back to Arvo in the form of
80another `move` to perform and the loop begins again. Thus this move trace does
81not display information about what is going on inside of the vane or app such as
82private function calls, only what the kernel itself sees.
84## Interpreting the move trace
86In this section we will go over the move trace line-by-line, explaining how the
87move trace is printed, what each line means (including some things not found in
88the move trace), and a particular focus on what code is being activated in the
89first few lines that should equip you well enough to unravel the rest of the
90move trace in as much detail as you desire.
93### The call
95Let's put the first part of the move trace into a diagram to make following
96along a little easier.
98<div style="text-align:center">
99<img src="https://media.urbit.org/docs/arvo/move-trace-with-key.png">
100</div>
102Here, each arrow represents the passing of some information, with most of it
103being from vane to vane. Here, when Vane A has an arrow to a card and then an
104arrow to Vane B, this represents either a `%pass` `note/task` sequence or a
105`%give` `gift/sign` sequence that actually has the Arvo kernel in the middle.
106That is to say, Vane A `%pass`es a `note` to the Arvo kernel addressed to Vane
107B, and the Arvo kernel then `%pass`es a `task` to Vane B. For more information,
108see the [Arvo kernel tutorial](/docs/arvo/overview#the-kernel).
110This simple action ends up involving four vanes - Dill, Gall, Behn, and Ford -
111as well as four applications - hood, spider, dojo, and time.
113Now let's go through each line one by one.
114```
115["" %unix p=%belt //term/1 ~2020.1.14..19.01.25..7556]
116```
117This tells us that Unix has sent a `%belt` `card`, which corresponds to
118terminal input (the Enter keystroke) at time `~2020.1.14..19.01.25..7556`
120Here is the line of code in `arvo.hoon`, found in the [section
1213bE core](/docs/arvo/overview#section-3be-core), that generated the output:
123```hoon
124 ~? !lac ["" %unix -.q.ovo p.ovo now]
125```
126First we note that this line is executed only if the laconic bit is set to true,
127as we did when we input `|verb`. Here, `ovo` is the input `ovum`. Knowing that an `ovum` is a `[p=wire q=curd]`,
128we can then say that this is a `%unix` `move` tagged with `%belt` whose cause is a `wire` given by `//term/1`,
129where the empty span `//` represents Unix and `term/1` represents the terminal
130in Unix. Here we have a `wire` instead of a `duct` (i.e. a list of `wire`s)
131since Unix I/O events are always the beginning and end of the Arvo event loop,
132thus only a single `wire` is ever required at this initial stage.
134The `""` here is a metadatum that keeps track of how many steps deep in the
135causal chain the event is. An event
136with `n` `|`'s was caused by the most recent previous event with `n-1` `|`'s. In
137this case, Unix events are an "original cause" and thus represented by an empty
138string.
140At this point in time, Dill has received the `move` and then processes it. The
141`%belt` `task` in `dill.hoon` is `+call`ed, which is processed using the `+send`
142arm:
144```hoon
145 ++ send :: send action
146 |= bet/dill-belt
147 ^+ +>
148 ?^ tem
149 +>(tem `[bet u.tem])
150 (deal / [%poke [%dill-belt -:!>(bet) bet]])
151```
153Dill has taken in the command and in response it `%pass`es a `task` `card` with
154instructions to `%poke` hood, which is a Gall app
155primarily used for interfacing with Dill. Here, `+deal` is an arm for
156`%pass`ing a `card` to Gall to ask it to create a `%deal` `task`:
159```hoon
160 ++ deal :: pass to %gall
161 |= [=wire =deal:gall]
162 (pass wire [%g %deal [our our] ram deal])
163```
165Next in our move trace we have this:
166```
167["|" %pass [%d %g] [[%deal [~zod ~zod] %hood %poke] /] [i=//term/1 t=~]]
168```
169Here, Dill `%pass`es a `task` `card` saying to `%poke` Gall's hood app (with the
170Enter keystroke).
172Let's glance at part of the `+jack` arm in `arvo.hoon`, located in the [section 3bE
173core](/docs/arvo/overview#section-3be-core). This arm is what the Arvo kernel uses to send `card`s,
174and here we look at the segment that includes `%pass` `move`s.
176```hoon
177 ++ jack :: dispatch card
178 |= [lac=? gum=muse]
179 ^- [[p=(list ovum) q=(list muse)] _vanes]
180 ~| %failed-jack
181 :: =. lac |(lac ?=(?(%g %f) p.gum))
182 :: =. lac &(lac !?=($b p.gum))
183 %^ fire
184 p.gum
185 s.gum
186 ?- -.r.gum
187 $pass
188 ~? &(!lac !=(%$ p.gum))
189 :- (runt [s.gum '|'] "")
190 :^ %pass [p.gum p.q.r.gum]
191 ?: ?=(?(%deal %deal-gall) +>-.q.q.r.gum)
192 :- :- +>-.q.q.r.gum
193 (,[[ship ship] term term] [+>+< +>+>- +>+>+<]:q.q.r.gum)
194 p.r.gum
195 [(symp +>-.q.q.r.gum) p.r.gum]
196 q.gum
197 [p.q.r.gum ~ [[p.gum p.r.gum] q.gum] q.q.r.gum]
198```
200Code for writing traces can be a bit tricky, but let's try not to get too
201distracted by the lark expressions and such. By paying attention to the lines
202concerning the laconic bit (following `!lac`) we can mostly determine what is being told to us.
204From the initial input event, Arvo has generated a `card` that it is now
205`%pass`ing from Dill (represented by `%d`) to Gall (represented by `%g`). The
206`card` is a `%deal` `task`, asking Gall to `%poke` hood using data that has
207originated from the terminal `//term/1`, namely that the Enter key was pressed. The line `:- (runt [s.gum '|'] "")`
208displays the causal chain length metadatum mentioned above. Lastly, `[~zod ~zod]` tells us that
209`~zod` is both the sending and receiving ship.
211From here on our explanations will be more brief. We include some information
212that cannot be directly read from the move trace in [brackets]. Onto the next line:
214```
215["||" %pass [%g %g] [[%deal [~zod ~zod] %dojo %poke] /use/hood/~zod/out/~zod/dojo/drum/phat/~zod/dojo] [i=/d t=~[//term/1]]]
216```
218Here is another `%pass` `move`, this time from Gall to iself as denoted by `[%g
219%g]`. Gall's hood has received the `%deal` `card` from Dill, and in response it is
220`%poke`ing dojo with the information [that Enter was pressed].
222```
223["|||" %give %g [%unto %fact] [i=/g/use/hood/~zod/out/~zod/dojo/drum/phat/~zod/dojo t=~[/d //term/1]]]
224```
226Gall's dojo `%give`s a `gift` with a `%fact` (subscription update) to Gall's hood, [saying to clear
227the terminal prompt].
229```
230["||||" %give %g [%unto %fact] [i=/d t=~[//term/1]]]
231```
232Gall's hood `%give`s a `gift` with a `%fact` to Dill [saying to replace the current terminal line with `~zod:dojo>`]
234Next is the `move` that is not actually printed in the move trace mentioned
235above:
237```
238["|||||" %give %d %blit [i=//term/1 t=~]]
239```
241Dill `%give`s a `%blit` (terminal output) event to Unix [saying to replace the current terminal line with `~zod:dojo>`].
243```
244["|||" %pass [%g %f] [%build /use/dojo/~zod/drum/hand] [i=/d t=~[//term/1]]]
245```
247Gall's dojo also `%pass`es a `%build` request to Ford [asking to run "~s1" against the subject we use in the dojo].
249```
250["||||" %give %f %made [i=/g/use/dojo/~zod/drum/hand t=~[/d //term/1]]]
251```
253Ford `%give`s a result back to dojo [with the value `~s1`]
255```
256["|||||" %pass [%g %g] [[%deal [~zod ~zod] %spider %watch] /use/dojo/~zod/out/~zod/spider/drum/wool] [i=/d t=~[//term/1]]]
257```
259Gall's dojo `%pass`es a `%watch` to Gall's spider app [to start listening for the result of the thread it's about to start].
261```
262["||||||" %give %g [%unto %watch-ack] [i=/g/use/dojo/~zod/out/~zod/spider/drum/wool t=~[/d //term/1]]]
263```
265Gall's spider acknowledges the subscription from dojo.
267```
268["|||||" %pass [%g %g] [[%deal [~zod ~zod] %spider %poke] /use/dojo/~zod/out/~zod/spider/drum/wool] [i=/d t=~[//term/1]]]
269```
271Gall's dojo also `%pass`es a `%poke` to Gall's spider [asking it start the thread "-time" with argument `~s1`].
273```
274["||||||" %pass [%g %f] [%build /use/spider/~zod/find/~.dojo_0v6.210tt.1sme1.ev3qm.qgv2e.a754u] [i=/d t=~[//term/1]]]
275```
277Gall's spider `%pass`es a `%build` request to Ford [asking it to find the path in `/ted` where the "time" thread is].
279```
280["|||||||" %give %f %made [i=/g/use/spider/~zod/find/~.dojo_0v6.210tt.1sme1.ev3qm.qgv2e.a754u t=~[/d //term/1]]]
281```
283Ford `%give`s a result back to Gall's spider [saying it's in `/ted/time.hoon`].
285```
286["||||||||" %pass [%g %f] [%build /use/spider/~zod/build/~.dojo_0v6.210tt.1sme1.ev3qm.qgv2e.a754u] [i=/d t=~[//term/1]]]
287```
289Gall's spider `%pass`es a `%build` request to Ford [asking it to compile the file `/ted/time.hoon`].
291```
292["|||||||||" %give %f %made [i=/g/use/spider/~zod/build/~.dojo_0v6.210tt.1sme1.ev3qm.qgv2e.a754u t=~[/d //term/1]]]
293```
295Ford `%give`s a result back to Gall's spider [with the compiled thread].
297```
298["||||||||||" %pass [%g %b] [%wait /use/spider/~zod/thread/~.dojo_0v6.210tt.1sme1.ev3qm.qgv2e.a754u/wait/~2020.1.14..19.01.26..7556] [i=/d t=~[//term/1]]]
299```
301Gall's spider's thread with id `~.dojo_0v6.210tt.1sme1.ev3qm.qgv2e.a754u` asks Behn to set a timer [for one second].
303```
304["|||||||||||" %give %b %doze [i=//behn/0v1p.sn2s7 t=~]]
305```
307Behn `%give`s a `%doze` `card` to Unix, asking it to set a timer [for one second from
308now]. At this point Arvo may rest.
310### The return
312Now Unix sets a timer for one second, waits one second, and then informs Behn that a second has
313passed, leading to a chain of `%give` `move`s that ultimately prints
314`~s1..0007`.
316Let's throw the move trace into a table:
318| length | move | vane(s) | card | duct |
319|--------|---------|---------|-----------------|------------------------------------------------------------------------------------------------------------------|
320| 0 | `%unix` | | `%wake` | `//behn` |
321| 1 | `%give` | `%b` | `%doze` | `//behn/0v1p.sn2s7` |
322| 1 | `%give` | `%b` | `%wake` | `/g/use/spider/~zod/thread/~.dojo_0v6.210tt.1sme1.ev3qm.qgv2e.a754u/wait/~2020.1.14..19.01.26..7556 /d //term/1` |
323| 2 | `%give` | `%g` | `[%unto %fact]` | `/g/use/dojo/~zod/out/~zod/spider/drum/wool /d //term/1` |
324| 3 | `%give` | `%g` | `[%unto %fact]` | `/g/use/hood/~zod/out/~zod/dojo/drum/phat/~zod/dojo /d //term/1` |
325| 4 | `%give` | `%g` | `[%unto %fact]` | `/d //term/1` |
326| 5 | `%give` | `%d` | `%blit` | `//term/1` |
327| 2 | `%give` | `%g` | `[%unto %kick]` | `/g/use/dojo/~zod/out/~zod/spider/drum/wool /d //term/1` |
329Now we follow it line-by-line:
331```
332["" %unix p=%wake //behn ~2020.1.14..19.01.26..755d]
333```
335Unix sends a `%wake` (timer fire) `card` at time `~2020.1.14..19.01.26..755d`.
337```
338["|" %give %b %doze [i=//behn/0v1p.sn2s7 t=~]]
339```
341Behn `%give`s a `%doze` `card` to Unix, asking it to set a timer [for whatever next timer it has in its queue].
343```
344["|" %give %b %wake [i=/g/use/spider/~zod/thread/~.dojo_0v6.210tt.1sme1.ev3qm.qgv2e.a754u/wait/~2020.1.14..19.01.26..7556 t=~[/d //term/1]]]
345```
347Behn `%give`s a `%wake` to Gall's spider's thread with id `~.dojo_0v6.210tt.1sme1.ev3qm.qgv2e.a754u`.
349```
350["||" %give %g [%unto %fact] [i=/g/use/dojo/~zod/out/~zod/spider/drum/wool t=~[/d //term/1]]]
351```
353Gall's spider `%give`s a `%fact` (subscription update) to dojo [saying that the thread completed successfully and produced value `~s1.0007`].
355```
356["|||" %give %g [%unto %fact] [i=/g/use/hood/~zod/out/~zod/dojo/drum/phat/~zod/dojo t=~[/d //term/1]]]
357```
359Gall's dojo `%give`s a `%fact` to hood [saying to output `~s1..0007`].
361```
362["||||" %give %g [%unto %fact] [i=/d t=~[//term/1]]]
363```
365Gall's hood `%give`s a `%fact` to Dill [saying to output `~s1..0007`].
367```
368["|||||" %give %d %blit [i=//term/1 t=~]]
369```
371Dill `%give`s a `%blit` (terminal output) event to Unix [saying to print a new line with output `~s1..0007`].
373```
374["||" %give %g [%unto %kick] [i=/g/use/dojo/~zod/out/~zod/spider/drum/wool t=~[/d //term/1]]]
375```
377Gall's spider also closes the subscription from dojo [since the thread has completed].