@@ -0,0 +1,108 @@
1++++
2+title = "2.6 Behn"
3+weight = 33
4+template = "doc.html"
5++++
6+
7+In this lesson we introduce the notion of a vane, which should be thought of as a kernel module for Arvo (if you don't know what that means yet, just keep reading). We first present a primer on what vanes are and how they communicate, followed by an examination of the simplest vane, known as Behn (pronounced like "bane"), which is Arvo's timekeeper.
8+
9+Following this lesson, we will introduce Gall, a vane used to build user space apps. Then we have a walkthrough where we construct an [egg timer](@docs/learn/hoon/hoon-tutorial/egg-timer/) as a Gall app that interacts with Behn.
10+
11+## Vanes
12+
13+In order to introduce vanes, we must first introduce the concept of a [kernel](https://en.wikipedia.org/wiki/Kernel_(operating_system)). The kernel is in some sense the "core" of an operating system, in that it has complete control over all events in the system and may perform any operation. It is the first part of the operating system to boot, and is responsible for spawning all other processes and routing their communication to one another. The tasks a kernel performs are very low level - managing memory, prioritizing processes, keeping track of time, managing hardware I/O, etc.
14+
15+Kernel code is generally kept to be as minimal as possible, and so almost anything non-trivial is put into an extension called a kernel module. **Vanes** are kernel modules for Arvo. Arvo currently has eight vanes known as Ames, Behn, Clay, Dill, Eyre, Ford, Gall, and Hall. You can read a short description of each one in [learn/arvo](@/docs/learn/arvo.md), along with a more thorough explanation of how vanes communicate than the following.
16+
17+Vanes communicate with one another by exchanging chunks of data known as `move`s. We will get into more detail above what a `move` is in our example of Behn below, (and also see [learn/arvo](@/docs/learn/arvo.md)) but at a high level one should think of a `move` as either a request from one vane to another or a response to a request. In our egg timer app, Gall and Behn will be exchanging `move`s.
18+
19+Notably, vanes are _not_ something that a user ever interacts with directly. They live in an area of the memory called "kernel space", while all user processes live in [user space](https://en.wikipedia.org/wiki/User_space). Applications in user space make _system calls_ to the kernel, which the kernel may or may not obey (for security and stability purposes). These requests could be things such as asking for the time, getting the input of a hardware device, making an http request, or moving a file. In our egg timer app, we will be making system calls to ask Behn to handle the timer aspect.
20+
21+## Behn
22+
23+In this section we introduce the simplest Arvo vane, Behn. This is not exhaustive, but just enough to know what is going on inside of Behn when we make a system call to it in the egg timer app. We discuss relevant types, some arms that are only called internally, and arms that may be called by another vane via a `move`.
24+
25+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.
26+
27+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.
28+
29+### Types
30+
31+We review here some of the commonly used types in the Behn vane as found in `behn.hoon`.
32+
33+#### `timer`
34+```
35++$ timer [date=@da =duct]
36+```
37+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:
38+#### `behn-state`
39+```hoon
40++$ behn-state
41+ $: timers=(list timer)
42+ unix-duct=duct
43+ next-wake=(unit @da)
44+ drips=drip-manager
45+ ==
46+```
47+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.
48+
49+#### `move`
50+
51+Arvo vanes communicate via `moves`:
52+```hoon
53++$ move [p=duct q=(wind note gift:able)]
54+```
55+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`:
56+
57+```hoon
58+++ wind :: new kernel action
59+ |* [a=mold b=mold] :: forward+reverse
60+ $% [%pass p=path q=a] :: advance
61+ [%slip p=a] :: lateral
62+ [%give p=b] :: retreat
63+ ==
64+```
65+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 callee.
66+
67+
68+### Internal arms
69+
70+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.
71+
72+#### ++set-unix-wake
73+This arm is what Behn uses to tell the unix timer when to `%wake` Behn.
74+
75+#### ++set-timer
76+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.
77+
78+#### ++wait
79+```hoon
80+++ wait |=(date=@da set-unix-wake(timers.state (set-timer [date duct])))
81+```
82+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.
83+
84+#### ++rest
85+```hoon
86+++ rest |=(date=@da set-unix-wake(timers.state (unset-timer [date duct])))
87+```
88+This undoes a `++wait` operation. That is, `++rest` removes a timer from the list of `timer`s.
89+
90+#### ++wake
91+This arm is ultimately called by the unix timer to let Behn know that a previously specified amount of time has elapsed.
92+
93+#### ++born
94+
95+```hoon
96+++ born set-unix-wake(next-wake.state ~, unix-duct.state duct)
97+```
98+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.
99+
100+### External interface
101+
102+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`.
103+
104+#### ++call
105+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`.
106+
107+#### ++take
108+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.