@@ -1,20 +1,94 @@
2title = "Behn"
2title = "Behn"
4template = "doc.html"
4template = "doc.html"
5−aliases = ["/docs/learn/arvo/behn/"]
9−It allows vanes and applications to set and timer events, which are
7+Behn is an Arvo vane that acts as a simple timer. It allows vanes and applications to set timer events, which are managed in a simple priority queue.
10−managed in a simple priority queue. `%behn` produces effects to start
8+
11−the unix timer, and when the requested `%behn` passes, unix sends wake
9+An app or vane can make a request to Behn to be informed when a specified amount of time has elapsed. Behn then produces effects to begin a unix timer for that request. The unix timer informs Behn after the specified time has elapses, which then informs the requestee. There is no guarantee that the requestee will be informed of the elapsed timer at the precise moment it requested, or even that it will be close. The only guarantee is that the requester will be informed at some point after the allotted time has passed.
12−events to `%behn`, which time routes back to original sender. We don't
10+
13−guarantee that a timer event will happen at exactly the `%behn` it was
11+## Types
14−set for, or even that it'll be particularly close. A timer event is a
12+
15−request to not be woken until after the given time.
13+We review here some of the commonly used types in the Behn vane as found in `behn.hoon`.
17−`%eyre` uses `%behn` for timing out sessions, and `%clay` uses `%behn`
15+### `timer`
18−for keeping track of time-specified file requests. `%ames` should
16+```
19−probably use `%behn` to keep track of things like network timeouts and
17++$ timer [date=@da =duct]
20−retry timing, but it currently uses its own alarm system.
18+```
20+A `timer` consists of a `@da` (an absolute date at which the timer will go off) and a `duct` (representing the causal stack that began the timer). As part of its state, `Behn` keeps track of a list of `timer`s.
26+ $: timers=(list timer)
33+We see that a `behn-state` is a list of all `timers` that `Behn` is currently keeping track of. `unix-duct` is Behn's link to the unix timer. `next-wake` is the next time that `Behn` is supposed to inform a requestee that the specified timer has elapsed. We will ignore `drips` for the purpose of this tutorial.
37+Arvo vanes communicate via `moves`:
39++$ move [p=duct q=(wind note gift:able)]
41+A `duct` is a call stack, which is a list of `path`s that represent a step in a causal chain of events. A `wind` is a kernel action. See the following arm from `arvo.hoon`:
44+++ wind :: new kernel action
45+ |* [a=mold b=mold] :: forward+reverse
46+ $% [%pass p=path q=a] :: advance
47+ [%slip p=a] :: lateral
48+ [%give p=b] :: retreat
52+Here we see that `wind` produces a wet gate that takes in two molds, which for the `move` type for Behn are `note`s and `gift`s. When a vane needs to request something of another vane, it `%pass`es a `note`. When a vane produces a result that was requested, it `%gives` a `gift` to the caller.
56+The following arms are part of the `event-core` of Behn, which are essentially the internal functions of the Behn vane that are not directly accessible to other vanes and applications. We will not review all of them here, we only list some of most important ones.
59+This arm is what Behn uses to tell the unix timer when to `%wake` Behn.
62+This arm is a dry gate that takes in a `timer` and adds it to the list of `timer`s in the `state`. ``++set-timer`` automatically places the new `timer` in chronological order, so that the timer at the front of the list of `timer`s is the `timer` that will expire the soonest.
66+++ wait |=(date=@da set-unix-wake(timers.state (set-timer [date duct])))
68+This arm is called when Behn is `%pass`ed a `note` telling Behn to `%wait`. This adds a `timer` to the list of `timer`s in the `state` and correspondingly tells the unix timer to tell Behn when the specified time has passed.
72+++ rest |=(date=@da set-unix-wake(timers.state (unset-timer [date duct])))
74+This undoes a `++wait` operation. That is, `++rest` removes a timer from the list of `timer`s.
77+This arm is ultimately called by the unix timer to let Behn know that a previously specified amount of time has elapsed.
82+++ born set-unix-wake(next-wake.state ~, unix-duct.state duct)
84+This arm is called when Behn is first launched. It gives Behn a `duct` to the unix timer and initializes the `behn-state` with the face `state` with a null list of `timer`s.
88+Arvo talks to Behn via four arms, `++call`, `++load`, `++scry`, `++stay`, and ``++take``, which ultimately call arms in the `event-core` of which we have listed a subset above. Here we will only look at `++call` and `++take`.
91+When Behn is `%pass`ed a `note` from another vane, that is enacted upon by Arvo via the `++call` gate. The `note` specifies what action to take, which are references to the internal arms. This is done by including in the `note` a symbol such as `%born`, `%rest`, `%wait`, or `%wake`, which ultimately call the arms with those names in the `event-core`.
94+When Behn is ready to inform another vane or application that a timer has elapsed, Arvo activates the `++take` gate. That is, Arvo `take`s a `gift` from Behn that includes the symbol `%wake`, and `%pass`es it to the the requestee. `%wake` is the only kind of `gift` that Behn can make, but other vanes may possess multiple responses.