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