@@ -1,6 +1,8 @@
11---
22navhome: /docs/
3+next: true
34sort: 22
5+Title: Internals
46---
57
68# Arvo internals
@@ -11,13 +13,13 @@ Arvo is composed of modules called vanes:
1113
1214<hr></hr>
1315
14−At a high level `%arvo` takes a mess of unix io events and turns them
16+At a high level `%arvo` takes a mess of Unix I/O events and turns them
1517into something clean and structured for the programmer.
1618
1719`%arvo` is designed to avoid the usual state of complex event networks:
1820event spaghetti. We keep track of every event's cause so that we have a
1921clear causal chain for every computation. At the bottom of every chain
20−is a unix io event, such as a network request, terminal input, file
22+is a Unix I/O event, such as a network request, terminal input, file
2123sync, or timer event. We push every step in the path the request takes
2224onto the chain until we get to the terminal cause of the computation.
2325Then we use this causal stack to route results back to the caller.
@@ -29,7 +31,7 @@ The `%arvo` causal stack is called a `++duct`. This is represented
2931simply as a list of paths, where each path represents a step in the
3032causal chain. The first element in the path is the first letter of
3133whichever vane handled that step in the computation, or the empty span
32−for unix.
34+for Unix.
3335
3436Here's a duct that was recently observed in the wild:
3537
@@ -44,20 +46,20 @@ Here's a duct that was recently observed in the wild:
4446This is the duct the timer vane receives when "timer" sample app asks
4547the timer vane to set a timer. This is also the duct over which the
4648response is produced at the specified time. Unix sent a terminal
47−keystroke event (enter), and arvo routed it to %dill(our terminal),
48−which passed it on to the %gall app terminal, which sent it to shell,
49+keystroke event (enter), and Arvo routed it to `%dill` (our terminal),
50+which passed it on to the `%gall` app terminal, which sent it to shell,
4951its child, which created a new child (with process id 4), which on
5052startup asked the timer vane to set a timer.
5153
5254The timer vane saves this duct, so that when the specified time arrives
53−and unix sends a wakeup event to the timer vane, it can produce the
55+and Unix sends a wakeup event to the timer vane, it can produce the
5456response on the same duct. This response is routed to the place we
5557popped off the top of the duct, i.e. the time app. This app produces the
5658text "ding", which falls down to the shell, which drops it through to
5759the terminal. Terminal drops this down to dill, which converts it into
58−an effect that unix will recognize as a request to print "ding" to the
60+an effect that Unix will recognize as a request to print "ding" to the
5961screen. When dill produces this, the last path in the duct has an
60−initial element of the empty span, so this is routed to unix, which
62+initial element of the empty span, so this is routed to Unix, which
6163applies the effects.
6264
6365This is a call stack, with a crucial feature: the stack is a first-class
@@ -90,42 +92,42 @@ caller.
9092Vanes
9193-----
9294
93−As shown above, we use arvo proper to route and control the flow of
94−moves. However, arvo proper is rarely directly responsible for
95+As shown above, we use Arvo proper to route and control the flow of
96+moves. However, Arvo proper is rarely directly responsible for
9597processing the event data that directly causes the desired outcome of a
9698move. This event data is contained within a card, which is simply a
97−`(pair term noun)`. Instead, arvo proper passes the card off to one of
99+`(pair term noun)`. Instead, Arvo proper passes the card off to one of
98100its vanes, which each present an interface to clients for a particular
99101well-defined, stable, and general-purpose piece of functionality.
100102
101103As of this writing, we have seven vanes, which each provide the
102104following services:
103105
104−- `%ames` name of both our network and the vane that communicates over
105− it
106−- `%behn` a simple timer
107−- `%clay` version-controlled, referentially- transparent, and global
108− filesystem
109−- `%dill` terminal driver. Unix sends keyboard events to `%dill` from
106+- `%ames`: the name of both our network and the vane that communicates over
107+ it.
108+- `%behn`: a simple timer.
109+- `%clay`: our version-controlled, referentially- transparent, and global
110+ filesystem.
111+- `%dill`: a terminal driver. Unix sends keyboard events to `%dill` from
110112 either the console or telnet, and `%dill` produces terminal output.
111−- `%eyre` http server. Unix sends http messages to `%eyre`, and
112− `%eyre` produces http messages in response
113−- `%ford` handles resources and publishing
114−- `%gall` manages our userspace applications. `%gall` keeps state and
115− manages subscribers
113+- `%eyre`: an http server. Unix sends http messages to `%eyre`, and
114+ `%eyre` produces http messages in response.
115+- `%ford`: handles resources and publishing.
116+- `%gall`: manages our userspace applications. `%gall` keeps state and
117+ manages subscribers.
116118
117119Cards
118120-----
119121
120122Cards are the vane-specific portion of a move. Each vane defines a
121−protocol for interacting with other vanes (via arvo) by defining four
123+protocol for interacting with other vanes (via Arvo) by defining four
122124types of cards: kisses, gifts, notes, and signs.
123125
124−When one vane is `%pass`ed a card in its `++kiss`, arvo activates the
126+When one vane is `%pass`ed a card in its `++kiss`, Arvo activates the
125127`++call` gate with the card as its argument. To produce a result, the
126128vane `%give`s one of the cards defined in its `++gift`. If the vane
127129needs to request something of another vane, it `%pass`es it a `++note`
128−card. When that other vane returns a result, arvo activates the `++take`
130+card. When that other vane returns a result, Arvo activates the `++take`
129131gate of the initial vane with one of the cards defined in its `++sign`.
130132
131133In other words, there are only four ways of seeing a move: (1) as a
@@ -134,12 +136,12 @@ seen by the callee, a `++kiss`. (3) the response to that first request
134136as seen by the callee, a `++gift`. (4) the response to the first request
135137as seen by the caller, a `++sign`.
136138
137−When a `++kiss` card is passed to a vane, arvo calls its `++call` gate,
139+When a `++kiss` card is passed to a vane, Arvo calls its `++call` gate,
138140passing it both the card and its duct. This gate must be defined in
139141every vane. It produces two things in the following order: a list of
140−moves and a possibly-modified copy of its context. The moves are used to
142+moves and a possibly modified copy of its context. The moves are used to
141143interact with other vanes, while the new context allows the vane to save
142−its state. The next time arvo activates the vane it will have this
144+its state. The next time Arvo activates the vane it will have this
143145context as its subject.
144146
145147This overview has detailed how to pass a card to a particular vane. To