@@ -0,0 +1,150 @@
1+---
2+sort: 3
3+---
4+
5+arvo
6+====
7+
8+Our operating system.
9+
10+arvo is composed of modules called vanes:
11+
12+<list dataPreview="true"></list>
13+
14+<hr></hr>
15+
16+At a high level `%arvo` takes a mess of unix io events and turns them
17+into something clean and structured for the programmer.
18+
19+`%arvo` is designed to avoid the usual state of complex event networks:
20+event spaghetti. We keep track of every event's cause so that we have a
21+clear causal chain for every computation. At the bottom of every chain
22+is a unix io event, such as a network request, terminal input, file
23+sync, or timer event. We push every step in the path the request takes
24+onto the chain until we get to the terminal cause of the computation.
25+Then we use this causal stack to route results back to the caller.
26+
27+`++ducts`
28+---------
29+
30+The `%arvo` causal stack is called a `++duct`. This is represented
31+simply as a list of paths, where each path represents a step in the
32+causal chain. The first element in the path is the first letter of
33+whichever vane handled that step in the computation, or the empty span
34+for unix.
35+
36+Here's a duct that was recently observed in the wild:
37+
38+ ~[
39+ /g/a/~zod/4_shell_terminal/u/time
40+ /g/a/~zod/shell_terminal/u/child/4/main
41+ /g/a/~zod/terminal/u/txt
42+ /d/term-mess
43+ //term/1
44+ ]
45+
46+This is the duct the timer vane receives when "timer" sample app asks
47+the timer vane to set a timer. This is also the duct over which the
48+response is produced at the specified time. Unix sent a terminal
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,
51+its child, which created a new child (with process id 4), which on
52+startup asked the timer vane to set a timer.
53+
54+The timer vane saves this duct, so that when the specified time arrives
55+and unix sends a wakeup event to the timer vane, it can produce the
56+response on the same duct. This response is routed to the place we
57+popped off the top of the duct, i.e. the time app. This app produces the
58+text "ding", which falls down to the shell, which drops it through to
59+the terminal. Terminal drops this down to dill, which converts it into
60+an effect that unix will recognize as a request to print "ding" to the
61+screen. When dill produces this, the last path in the duct has an
62+initial element of the empty span, so this is routed to unix, which
63+applies the effects.
64+
65+This is a call stack, with a crucial feature: the stack is a first-class
66+citizen. You can respond over a duct zero, one, or many times. You can
67+save ducts for later use. There are definitely parallels to Scheme-style
68+continuations, but simpler and with more structure.
69+
70+Making Moves
71+------------
72+
73+If ducts are a call stack, then how do we make calls and produce
74+results? Arvo processes "moves" which are a combination of message data
75+and metadata. There are two types of moves. A `%pass` move is analogous
76+to a call:
77+
78+ [duct %pass return-path=path vane-name=@tD data=card]
79+
80+Arvo pushes the return path (preceded by the first letter of the vane
81+name) onto the duct and sends the given data, a card, to the vane we
82+specified. Any response will come along the same duct with the path
83+`return-path`.
84+
85+A `%give` move is analogous to a return:
86+
87+ [duct %give data=card]
88+
89+Arvo pops the top path off the duct and sends the given card back to the
90+caller.
91+
92+Vanes
93+-----
94+
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
97+processing the event data that directly causes the desired outcome of a
98+move. This event data is contained within a card, which is simply a
99+`(pair term noun)`. Instead, arvo proper passes the card off to one of
100+its vanes, which each present an interface to clients for a particular
101+well-defined, stable, and general-purpose piece of functionality.
102+
103+As of this writing, we have seven vanes, which each provide the
104+following services:
105+
106+- `%ames` name of both our network and the vane that communicates over
107+ it
108+- `%clay` version-controlled, referentially- transparent, and global
109+ filesystem
110+- `%dill` terminal driver. Unix sends keyboard events to `%dill` from
111+ either the console or telnet, and `%dill` produces terminal output.
112+- `%eyre` http server. Unix sends http messages to `%eyre`, and
113+ `%eyre` produces http messages in response
114+- `%ford` handles resources and publishing
115+- `%gall` manages our userspace applications.. `%gall` keeps state and
116+ manages subscribers
117+- `%time` a simple timer
118+
119+Cards
120+-----
121+
122+Cards are the vane-specific portion of a move. Each vane defines a
123+protocol for interacting with other vanes (via arvo) by defining four
124+types of cards: kisses, gifts, notes, and signs.
125+
126+When one vane is `%pass`ed a card in its `++kiss`, arvo activates the
127+`++call` gate with the card as its argument. To produce a result, the
128+vane `%give`s one of the cards defined in its `++gift`. If the vane
129+needs to request something of another vane, it `%pass`es it a `++note`
130+card. When that other vane returns a result, arvo activates the `++take`
131+gate of the initial vane with one of the cards defined in its `++sign`.
132+
133+In other words, there are only four ways of seeing a move: (1) as a
134+request seen by the caller, which is a ++note. (2) that same request as
135+seen by the callee, a `++kiss`. (3) the response to that first request
136+as seen by the callee, a `++gift`. (4) the response to the first request
137+as seen by the caller, a `++sign`.
138+
139+When a `++kiss` card is passed to a vane, arvo calls its `++call` gate,
140+passing it both the card and its duct. This gate must be defined in
141+every vane. It produces two things in the following order: a list of
142+moves and a possibly-modified copy of its context. The moves are used to
143+interact with other vanes, while the new context allows the vane to save
144+its state. The next time arvo activates the vane it will have this
145+context as its subject.
146+
147+This overview has detailed how to pass a card to a particular vane. To
148+see the cards each vane can be `%pass`ed as a `++kiss` or return as a
149+`++gift` (as well as the semantics tied to them), each vane's public
150+interface is explained in detail in its respective overview.