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