git.iko.soy/urbit.org
on 883cb21 help sign in
urbit.org/content/docs/userspace/threads/basics/input.md
145 lines 3.7 kB history raw
1+++
2title = "Input"
3weight = 3
4template = "doc.html"
5+++
7The input to a `strand` is defined in `/lib/strand/hoon` as:
9```hoon
10+$ strand-input [=bowl in=(unit input)]
11```
13When a thread is first started, spider will populate the `bowl` and provide it along with an `input` of `~`. If/when new input comes in (such as a poke, sign or watch) it will provide a new updated bowl along with the new input.
15For example, here's a thread that gets the time from the bowl, runs an IO-less function that takes one or two seconds to compute, and then gets the time again:
17```hoon
18/- spider
19/+ *strandio
20=, strand=strand:spider
21|%
22++ ackermann
23 |= [m=@ n=@]
24 ?: =(m 0) +(n)
25 ?: =(n 0) $(m (dec m), n 1)
26 $(m (dec m), n $(n (dec n)))
27--
28^- thread:spider
29|= arg=vase
30=/ m (strand ,vase)
31^- form:m
32;< t1=@da bind:m get-time
33=/ ack (ackermann 3 8)
34;< t2=@da bind:m get-time
35(pure:m !>([t1 t2]))
36```
38Since it never does any IO, `t1` and `t2` are the same: `[~2021.3.17..07.47.39..e186 ~2021.3.17..07.47.39..e186]`. However, if we replace the ackermann function with a 2 second `sleep` from strandio:
40```hoon
41/- spider
42/+ *strandio
43=, strand=strand:spider
44^- thread:spider
45|= arg=vase
46=/ m (strand ,vase)
47^- form:m
48;< t1=@da bind:m get-time
49;< ~ bind:m (sleep ~s2)
50;< t2=@da bind:m get-time
51(pure:m !>([t1 t2]))
52```
54...and run it again we get different values for `t1` and `t2`: `[~2021.3.17..07.50.28..8a5d ~2021.3.17..07.50.30..8a66]`. This is because `sleep` gets a `%wake` sign back from `behn`, so spider updates the time in the bowl along with it.
56Now let's look at the contents of `bowl` and `input` in detail:
58## bowl
60`bowl` is the following:
62```hoon
63+$ bowl
64 $: our=ship
65 src=ship
66 tid=tid
67 mom=(unit tid)
68 wex=boat:gall
69 sup=bitt:gall
70 eny=@uvJ
71 now=@da
72 byk=beak
73 ==
74```
76- `our` - our ship
77- `src` - ship where input is coming from
78- `tid` - ID of this thread
79- `mom` - parent thread if this is a child thread
80- `wex` - outgoing subscriptions
81- `sup` - incoming subscriptions
82- `eny` - entropy
83- `now` - current datetime
84- `byk` - `[p=ship q=desk r=case]` path prefix
86There are a number of functions in `strandio` to access the `bowl` contents like `get-bowl`, `get-beak`, `get-time`, `get-our` and `get-entropy`.
88You can also write a function with a gate whose sample is `strand-input:strand` and access the bowl that way like:
90```hoon
91/- spider
92/+ strandio
93=, strand=strand:spider
94=>
95|%
96++ bowl-stuff
97 =/ m (strand ,[boat:gall bitt:gall])
98 ^- form:m
99 |= tin=strand-input:strand
100 `[%done [wex.bowl.tin sup.bowl.tin]]
101--
102^- thread:spider
103|= arg=vase
104=/ m (strand ,vase)
105^- form:m
106;< res=[boat:gall bitt:gall] bind:m bowl-stuff
107(pure:m !>(res))
108```
110## input
112`input` is defined in libstrand as:
114```hoon
115+$ input
116 $% [%poke =cage]
117 [%sign =wire =sign-arvo]
118 [%agent =wire =sign:agent:gall]
119 [%watch =path]
120 ==
121```
123- `%poke` incoming poke
124- `%sign` incoming sign from arvo
125- `%agent` incoming sign from a gall agent
126- `%watch` incoming subscription
128Various functions in `strandio` will check `input` and conditionally do things based on its contents. For example, `sleep` sets a `behn` timer and then calls `take-wake` to wait for a `%wake` sign from behn:
130```hoon
131++ take-wake
132 |= until=(unit @da)
133 =/ m (strand ,~)
134 ^- form:m
135 |= tin=strand-input:strand
136 ?+ in.tin `[%skip ~]
137 ~ `[%wait ~]
138 [~ %sign [%wait @ ~] %behn %wake *]
139 ?. |(?=(~ until) =(`u.until (slaw %da i.t.wire.u.in.tin)))
140 `[%skip ~]
141 ?~ error.sign-arvo.u.in.tin
142 `[%done ~]
143 `[%fail %timer-error u.error.sign-arvo.u.in.tin]
144 ==
145```