git.iko.soy/urbit.org
on 514b5fc help sign in
urbit.org/content/docs/userspace/threads/basics/output.md
119 lines 3.5 kB history raw
1+++
2title = "Output"
3weight = 4
4template = "doc.html"
5+++
7A strand produces a `[(list card) <response>]`. The first part is a list of cards to be sent off immediately, and `<response>` is one of:
9- `[%wait ~]`
10- `[%skip ~]`
11- `[%cont self=(strand-form-raw a)]`
12- `[%fail err=(pair term tang)]`
13- `[%done value=a]`
15So, for example, if you feed `2 2` into the following function:
17```hoon
18 |= [a=@ud b=@ud]
19 =/ m (strand ,vase)
20 ^- form:m
21 =/ res !>(`@ud`(add a b))
22 (pure:m res)
23```
25The resulting strand won't just produce `[#t/@ud q=4]`, but rather `[~ %done [#t/@ud q=4]]`.
27**Note:** that spider doesn't actually return the codes themselves to thread subscribers, they're only used internally to manage the flow of the thread.
29Since a strand is a function from the previously discussed `strand-input` to the output discussed here, you can compose a valid strand like:
31```hoon
32|= strand-input:strand
33[~ %done 'foo']
34```
36So this is a valid thread:
38```hoon
39/- spider
40=, strand=strand:spider
41^- thread:spider
42|= arg=vase
43=/ m (strand ,vase)
44^- form:m
45|= strand-input:strand
46[~ %done arg]
47```
49As is this:
51```hoon
52/- spider
53=, strand=strand:spider
54|%
55++ my-function
56 =/ m (strand ,@t)
57 ^- form:m
58 |= strand-input:strand
59 [~ %done 'foo']
60--
61^- thread:spider
62|= arg=vase
63=/ m (strand ,vase)
64^- form:m
65;< msg=@t bind:m my-function
66(pure:m !>(msg))
67```
69As is this:
71```hoon
72/- spider
73=, strand=strand:spider
74^- thread:spider
75|= arg=vase
76=/ m (strand ,vase)
77^- form:m
78|= strand-input:strand
79=/ umsg !< (unit @tas) arg
80?~ umsg
81[~ %fail %no-arg ~]
82=/ msg=@tas u.umsg
83?. =(msg %foo)
84[~ %fail %not-foo ~]
85[~ %done arg]
86```
88Which works like:
90```
91> -mythread
92thread failed: %no-arg
93> -mythread %bar
94thread failed: %not-foo
95> -mythread %foo
96[~ %foo]
97```
99Now let's look at the meaning of each of the response codes.
101### wait
103Wait tells spider not to move on from the current strand, and to wait for some new input. For example, `sleep:strandio` will return a `[%wait ~]` along with a card to start a behn timer. Spider passes the card to behn, and when behn sends a wake back to spider, the new input will be given back to `sleep` as a `%sign`. Sleep will then issue `[~ %done ~]` and (assuming it's in a `bind`) `bind` will proceed to the next strand.
105### skip
107Spider will normally treat a `%skip` the same as a `%wait` and just wait for some new input. When used inside a `main-loop:strandio`, however, it will instead tell `main-loop` to skip this function and try the next one with the same input. This is very useful when you want to call different functions depending on the mark of a poke or some other condition.
109### cont
111Cont means continue computation. When a `%cont` is issued, the issuing gate will be called again with the new value provided. Therefore `%cont` essentially creates a loop.
113### fail
115Fail says to end the thread here and don't call any subsequent strands. It includes an error message and optional traceback. When spider gets a `%fail` it will send a fact with mark `%thread-fail` containing the error and traceback to its subscribers, and then end the thread.
117### done
119Done means the computation was completed successfully and includes the result. When `spider` recieves a `%done` it will send the result it contains in a fact with a mark of `%thread-done` to subscribers and end the thread. When `bind` receives a `%done` it will extract the result and call the next gate with it.