@@ -0,0 +1,248 @@
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.
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
29+`%born` does not return a `gift`.
34+`%crud` is called whenever an error involving Behn occurs, such as trying to
35+`%wake` a program that has crashed.
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`.
45+Here, `tag` is a `@tas` denoting the type of error, and `error` is an error message.
50+[%wake %behn-crud-no-timer tag error]
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.
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
67+`%drip` allows one to delay a `gift` until a timer set for `now` fires.
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:
73+Client -- %slip %drip --> Behn -- %pass %wait --> Behn -- %give %wake --> Behn -- %give %meta --> Target
75+Here the `%meta` `move` is a wrapper for the `%gift` inside of the initial `%drip` wrapper.
77+`%drip` only handles `gift`s, and can only schedule `gift`s for as soon as
78+possible after the prescribed timer fires.
87+`%drip` takes in a `%give` `move` in a `vase`.
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`.
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.
111+Immediately gives back an input move.
119+Behn takes in a `move` contained in a `vase`.
127+Behn returns the input `move` as a `%meta` `gift`.
133+Cancels a timer that was previously set.
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.
147+This `task` returns no `gift`s.
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.
158+This `task` has no arguments.
162+This task returns nothing.
166+This `task` informs the vane that the kernel has been upgraded. Behn does not do
167+anything in response to this.
171+This `task` has no arguments.
175+This `task` returns nothing.
181+This `task` takes in a `@da` which Behn then adds to `timers.state`, the list of timers.
191+This `task` returns a `%wake` `gift` once the timer has fired.
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.
201+Upon receiving this `task`, Behn processes the elapsed timer and then sets
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.
209+As a `task`, `%wake` takes in `~`.
211+As a `gift`, `%wake` may include an error message.
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.
228+This `task` asks Behn to product a memory usage report.
232+This `task` has no arguments.
240+ :~ timers+&+timers.state
244+When Behn is `%pass`ed this `task`, it will `%give` a `%mass` `gift` in response
245+containing Behn's current memory usage.