@@ -0,0 +1,248 @@
1++++
2+title = "Behn"
3+weight = 2
4+template = "doc.html"
5++++
6+
7+# Behn
8+
9+In this document we describe the public interface for Behn. Namely, we describe
10+each `task` that Behn can be `pass`ed, and which `gift`(s) Behn can `give` in return.
11+
12+
13+## Tasks
14+
15+### `%born`
16+
17+Each time you start your Urbit, the Arvo kernel calls the `%born` task for Behn. When
18+called, Behn gets the current time from Unix and updates its list of timers
19+accordingly.
20+
21+#### Accepts
22+
23+```hoon
24+[~]
25+```
26+
27+#### Returns
28+
29+`%born` does not return a `gift`.
30+
31+
32+### `%crud`
33+
34+`%crud` is called whenever an error involving Behn occurs, such as trying to
35+`%wake` a program that has crashed.
36+
37+When called, it checks to see if the set of timers is empty. If so, it prints
38+an error report containing `error`, otherwise it passes the error to `+wake`.
39+
40+#### Accepts
41+
42+```hoon
43+[tag=@tas error=tang]
44+```
45+Here, `tag` is a `@tas` denoting the type of error, and `error` is an error message.
46+
47+#### Returns
48+
49+```hoon
50+[%wake %behn-crud-no-timer tag error]
51+```
52+
53+If the set of timers is nonempty when Behn is `%pass`ed a `%crud` `task`, Behn
54+`%give`s a `%wake` `card` containing the error to the next client in the set of timers.
55+
56+
57+#### Example
58+
59+The most common error that occurs is when Behn tries to `%wake` up a program that has crashed. When this happens
60+the entire event (i.e. sequence of `move`s) that led up to the `%wake` is thrown
61+away, and Vere then causes the kernel to `pass` Behn a `%crud` `task` containing
62+the stack trace.
63+
64+
65+### `%drip`
66+
67+`%drip` allows one to delay a `gift` until a timer set for `now` fires.
68+
69+A Client `%slip`s Behn a `%drip` task wrapping a `gift` to be `give`n to a Target.
70+This launches a sequence of `move`s as written here:
71+
72+```
73+Client -- %slip %drip --> Behn -- %pass %wait --> Behn -- %give %wake --> Behn -- %give %meta --> Target
74+```
75+Here the `%meta` `move` is a wrapper for the `%gift` inside of the initial `%drip` wrapper.
76+
77+`%drip` only handles `gift`s, and can only schedule `gift`s for as soon as
78+possible after the prescribed timer fires.
79+
80+
81+#### Accepts
82+
83+```hoon
84+mov=vase
85+```
86+
87+`%drip` takes in a `%give` `move` in a `vase`.
88+
89+#### Returns
90+
91+In response to a `%drip` `task`, Behn will `%pass` a `%wait` to itself, which
92+then triggers a `%wake` `gift` to itself, which then causes Behn to `%give` a `%meta` `gift` containing
93+the `gift` originally `%give`n to Behn when `%drip` was first called. That makes
94+Behn its own client for `%drip`.
95+
96+#### Example
97+
98+
99+Say an app (the Target) is subscribed to updates from Clay (the Client). If Clay `%give`s
100+updates to the app directly and the app crashes, this may cause Clay to crash as
101+well. If instead Clay `%pass`es Behn a `%drip` `task` wrapping the update
102+`gift`, Behn will set a timer for `now` that, when fired, will cause the update
103+`gift` to be given. If it causes a crash then it will have been in response to
104+the `%drip` move, thereby isolating Clay from the crash. Thus `%drip` acts as a sort of buffer against cascading
105+sequences of crashes.
106+
107+
108+
109+### `%huck`
110+
111+Immediately gives back an input move.
112+
113+#### Accepts
114+
115+```hoon
116+mov=vase
117+```
118+
119+Behn takes in a `move` contained in a `vase`.
120+
121+#### Returns
122+
123+```hoon
124+[%give %meta mov]
125+```
126+
127+Behn returns the input `move` as a `%meta` `gift`.
128+
129+
130+
131+### `%rest`
132+
133+Cancels a timer that was previously set.
134+
135+Behn takes in a `@da` and cancels the timer at that time if it exists, then
136+adjusts the next wakeup call from Unix if necessary.
137+
138+#### Task
139+
140+```hoon
141+@da
142+```
143+
144+
145+#### Gift
146+
147+This `task` returns no `gift`s.
148+
149+
150+
151+### `%trim`
152+
153+This `task` is sent by the interpreter in order to free up memory.
154+ This `task` is empty for Behn, since it is not a good idea to forget your timers.
155+
156+#### Accepts
157+
158+This `task` has no arguments.
159+
160+#### Returns
161+
162+This task returns nothing.
163+
164+### `%vega`
165+
166+This `task` informs the vane that the kernel has been upgraded. Behn does not do
167+anything in response to this.
168+
169+#### Accepts
170+
171+This `task` has no arguments.
172+
173+#### Returns
174+
175+This `task` returns nothing.
176+
177+
178+
179+### `%wait`
180+
181+This `task` takes in a `@da` which Behn then adds to `timers.state`, the list of timers.
182+
183+#### Accepts
184+
185+```hoon
186+@da
187+```
188+
189+#### Returns
190+
191+This `task` returns a `%wake` `gift` once the timer has fired.
192+
193+
194+### `%wake`
195+
196+This `task` is sent by the kernel when the Unix timer tells the kernel that it
197+is time for Behn to wake up. This is often caused by a `%doze` `gift` that
198+Behn originally sent to the kernel that is then forwarded to Unix, which is
199+where the real timekeeping occurs.
200+
201+Upon receiving this `task`, Behn processes the elapsed timer and then sets
202+`:next-wake`.
203+
204+`%wake` is also a `gift` that Behn can `%give`. This is done to inform other
205+vanes or apps that a timer has expired, and may include an error message.
206+
207+#### Accepts
208+
209+As a `task`, `%wake` takes in `~`.
210+
211+As a `gift`, `%wake` may include an error message.
212+
213+```hoon
214+error=(unit tang)
215+```
216+
217+
218+#### Returns
219+
220+In response to receiving this `task`, Behn may `%give` a `%doze` `gift`
221+containing the `@da` of the next timer to elapse. Behn may also `%give` a
222+`%wake` `gift` to itself.
223+
224+
225+
226+### `%wegh`
227+
228+This `task` asks Behn to product a memory usage report.
229+
230+#### Accepts
231+
232+This `task` has no arguments.
233+
234+#### Returns
235+
236+```hoon
237+:_ state :_ ~
238+ :^ duct %give %mass
239+ :+ %behn %|
240+ :~ timers+&+timers.state
241+ dot+&+state
242+```
243+
244+When Behn is `%pass`ed this `task`, it will `%give` a `%mass` `gift` in response
245+containing Behn's current memory usage.
246+
247+
248+