git.iko.soy/urbit.org
on master help sign in
working through vanes
6f8cb1eGalen Wolfe-Pauly
docs/system/arvo.mdnew file+150
compare with master
unifiedsplit
@@ -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.
docs/system/arvo/ames.md+3−5
@@ -1,4 +1,6 @@
1−<div class="short">
1+---
2+sort: 1
3+---
2
4
3`%ames`
5`%ames`
4=======
6=======
@@ -22,8 +24,4 @@ routing is handled entirely in `%ames`. Finally, the actual `%ames`
22protocol itself, including how to route incoming packets to the correct
24protocol itself, including how to route incoming packets to the correct
23vane or app, is defined in `%ames`.
25vane or app, is defined in `%ames`.
24
26
25−</div>
26−
27−<hr>
28−</hr>
29<list></list>
27<list></list>
docs/system/arvo/ames/commentary.md+1−1
@@ -1812,4 +1812,4 @@ XXX
1812 ++ name ,[p=@t q=(unit ,@t) r=(unit ,@t) s=@t] :: first mid/nick last
1812 ++ name ,[p=@t q=(unit ,@t) r=(unit ,@t) s=@t] :: first mid/nick last
1813
1813
1814This is the given name, possible middle name/initial, possible nickname,
1814This is the given name, possible middle name/initial, possible nickname,
1815−and surname of a user.
1815+and surname of a user.
docs/system/arvo/behn.mdnew file+21
@@ -0,0 +1,21 @@
1+---
2+sort: 2
3+---
4+
5+`%behn`
6+=======
7+
8+Our simple timer.
9+
10+It allows vanes and applications to set and timer events, which are
11+managed in a simple priority queue. `%behn` produces effects to start
12+the unix timer, and when the requested `%behn` passes, unix sends wake
13+events to `%behn`, which time routes back to original sender. We don't
14+guarantee that a timer event will happen at exactly the `%behn` it was
15+set for, or even that it'll be particularly close. A timer event is a
16+request to not be woken until after the given time.
17+
18+`%eyre` uses `%behn` for timing out sessions, and `%clay` uses `%behn`
19+for keeping track of time-specified file requests. `%ames` should
20+probably use `%behn` to keep track of things like network timeouts and
21+retry timing, but it currently uses its own alarm system.
docs/system/arvo/clay.md+3−5
@@ -1,4 +1,6 @@
1−<div class="short">
1+---
2+sort: 3
3+---
2
4
3`%clay`
5`%clay`
4=======
6=======
@@ -20,8 +22,4 @@ zuse. Second is the write, query, and subscription logic. Finally, there
20is the logic for communicating requests to, and receiving requests from,
22is the logic for communicating requests to, and receiving requests from,
21foreign ships.
23foreign ships.
22
24
23−</div>
24−
25−------------------------------------------------------------------------
26−
27<list></list>
25<list></list>
docs/system/arvo/dill.md+4−6
@@ -1,4 +1,6 @@
1−<div class="short">
1+---
2+sort: 4
3+---
2
4
3`%dill`
5`%dill`
4=======
6=======
@@ -20,8 +22,4 @@ password), which duct to produce effects on, and so forth. Second, it
20handles terminal events, keystroke by keystroke. Most characters are
22handles terminal events, keystroke by keystroke. Most characters are
21simply pushed onto the buffer and blitted to the screen, but some
23simply pushed onto the buffer and blitted to the screen, but some
22characters, including control-modified keys, arrow keys, etc. require
24characters, including control-modified keys, arrow keys, etc. require
23−special handling. Most of the readline functionality is in `%dill`.
25+special handling. Most of the readline functionality is in `%dill`.
24−
25−</div>
26−
27−------------------------------------------------------------------------
docs/system/arvo/eyre.md+3−8
@@ -1,4 +1,6 @@
1−<div class="short">
1+---
2+sort: 5
3+---
2
4
3`%eyre`
5`%eyre`
4=======
6=======
@@ -16,10 +18,6 @@ essentially stateless, like functional publishing with `%ford`.
16Additionally, there's a fairly significant component that handles
18Additionally, there's a fairly significant component that handles
17`%gall` messaging and subscriptions, which must be stateful.
19`%gall` messaging and subscriptions, which must be stateful.
18
20
19−</div>
20−
21−------------------------------------------------------------------------
22−
23HTTP Methods
21HTTP Methods
24============
22============
25
23
@@ -57,7 +55,4 @@ Unsubscribe from stream `[stream]` on a foreign Urbit.
57urb.js
55urb.js
58======
56======
59
57
60−
61−<hr>
62−</hr>
63<list></list>
58<list></list>
docs/system/arvo/ford.md+19−36
@@ -1,4 +1,7 @@
1−<div class="short">
1+---
2+sort: 6
3+---
4+
2
5
3`%ford`
6`%ford`
4=======
7=======
@@ -19,16 +22,10 @@ while `%gall` uses `%ford` to control the execution of applications.
19`%clay` is intended to use `%ford` to managed marked data, but this is
22`%clay` is intended to use `%ford` to managed marked data, but this is
20not yet reality.
23not yet reality.
21
24
22−</div>
23−
24−------------------------------------------------------------------------
25−
26<list></list>
25<list></list>
27
26
28−------------------------------------------------------------------------
29−
30Cards
27Cards
31−=====
28+-----
32
29
33`%ford` accepts just one card, `%exec`. This is misleading, however,
30`%ford` accepts just one card, `%exec`. This is misleading, however,
34since there are fourteen different `silk`s that may be used with it. In
31since there are fourteen different `silk`s that may be used with it. In
@@ -39,90 +36,76 @@ dependencies.
39Silks may autocons, so that the product of a cell of silks is a cell of
36Silks may autocons, so that the product of a cell of silks is a cell of
40the product of the two silks.
37the product of the two silks.
41
38
42−`%bake`
39+### `%bake`
43−================
44
40
45Tries to functionally produce the file at a given beam with the given
41Tries to functionally produce the file at a given beam with the given
46mark and heel. It fails if there is no way to translate at this level.
42mark and heel. It fails if there is no way to translate at this level.
47
43
48−`%boil`
44+### `%boil`
49−================
50
45
51Functionally produces the file at a given beam with the given mark and
46Functionally produces the file at a given beam with the given mark and
52heel. If there is no way to translate at this beam, we pop levels off
47heel. If there is no way to translate at this beam, we pop levels off
53the stack and attempt to bake there until we find a level we can bake.
48the stack and attempt to bake there until we find a level we can bake.
54This should almost always be called instead of `%bake`.
49This should almost always be called instead of `%bake`.
55
50
56−`%call`
51+### `%call`
57−================
58
52
59Slams the result of one silk against the result of another.
53Slams the result of one silk against the result of another.
60
54
61−`%cast`
55+### `%cast`
62−================
63
56
64Translates the given silk to the given mark, if possible. This is one of
57Translates the given silk to the given mark, if possible. This is one of
65the critical and fundamental operations of ford.
58the critical and fundamental operations of ford.
66
59
67−`%diff`
60+### `%diff`
68−================
69
61
70Diffs the two given silks (which must be of the same mark), producing a
62Diffs the two given silks (which must be of the same mark), producing a
71cage of the mark specified in `++mark` in `++grad` for the mark of the
63cage of the mark specified in `++mark` in `++grad` for the mark of the
72two silks.
64two silks.
73
65
74−`%done`
66+### `%done`
75−================
76
67
77Produces exactly its input. This is rarely used on its own, but many
68Produces exactly its input. This is rarely used on its own, but many
78silks are recursively defined in terms of other silks, so we often need
69silks are recursively defined in terms of other silks, so we often need
79a silk that simply produces its input. A monadic return, if you will.
70a silk that simply produces its input. A monadic return, if you will.
80
71
81−`%dude`
72+### `%dude`
82−================
83
73
84Computes the given silk with the given tank as part of the stack trace
74Computes the given silk with the given tank as part of the stack trace
85if there is an error.
75if there is an error.
86
76
87−`%dune`
77+### `%dune`
88−================
89
78
90Produces an error if the cage is empty. Otherwise, it produces the value
79Produces an error if the cage is empty. Otherwise, it produces the value
91in the unit.
80in the unit.
92
81
93−`%mute`
82+### `%mute`
94−================
95
83
96Takes a silk and a list of changes to make to the silk. At each wing in
84Takes a silk and a list of changes to make to the silk. At each wing in
97the list we put the value of the associated silk.
85the list we put the value of the associated silk.
98
86
99−`%pact`
87+### `%pact`
100−================
101
88
102Applies the second silk as a patch to the first silk. The second silk
89Applies the second silk as a patch to the first silk. The second silk
103must be of the mark specified in `++mark` in `++grad` for the mark of
90must be of the mark specified in `++mark` in `++grad` for the mark of
104the first silk.
91the first silk.
105
92
106−`%plan`
93+### `%plan`
107−================
108
94
109Performs a structured assembly directly. This is not generally directly
95Performs a structured assembly directly. This is not generally directly
110useful because several other silks perform supersets of this
96useful because several other silks perform supersets of this
111functionality. We don't usually have naked hoods outside ford.
97functionality. We don't usually have naked hoods outside ford.
112
98
113−`%reef`
99+### `%reef`
114−================
115
100
116Produces a core containing the entirety of zuse and hoon, suitable for
101Produces a core containing the entirety of zuse and hoon, suitable for
117running arbitrary code against. The mark is `%noun`.
102running arbitrary code against. The mark is `%noun`.
118
103
119−`%ride`
104+### `%ride`
120−================
121
105
122Slaps a twig against a subject silk. The mark of the result is `%noun`.
106Slaps a twig against a subject silk. The mark of the result is `%noun`.
123
107
124−`%vale`
108+### `%vale`
125−================
126
109
127Validates untyped data from a ship against a given mark. This is an
110Validates untyped data from a ship against a given mark. This is an
128extremely useful function.
111extremely useful function.
docs/system/arvo/gall.md+21−50
@@ -1,4 +1,7 @@
1−<div class="short">
1+---
2+sort: 7
3+---
4+
2
5
3`%gall`
6`%gall`
4=======
7=======
@@ -20,27 +23,19 @@ applications. Eyre exposes `%gall`'s interface over http, and ames does
20the same over the ames network. `%gall` uses ford to compile and run the
23the same over the ames network. `%gall` uses ford to compile and run the
21applications.
24applications.
22
25
23−</div>
24−
25−------------------------------------------------------------------------
26−
27Cards
26Cards
28−=====
27+-----
29
28
30`%gall` accepts the following cards. The first three are the most
29`%gall` accepts the following cards. The first three are the most
31commonly used, while the others are primarily used internally.
30commonly used, while the others are primarily used internally.
32
31
33−`%mess`
32+### `%mess`
34−================
35
33
36Sends a message to an app. This will result in a call to the app's
34Sends a message to an app. This will result in a call to the app's
37`++poke` arm. The response is exactly one of a `%nice` if the action
35`++poke` arm. The response is exactly one of a `%nice` if the action
38succeeded or a `%mean` if not.
36succeeded or a `%mean` if not.
39
37
40−------------------------------------------------------------------------
41−
42−`%show`
38+### `%show`
43−================
44
39
45Subscribes to a stream from an app. This will result in a call to the
40Subscribes to a stream from an app. This will result in a call to the
46app's either `++peek` or `++peer` arm. The first response will always be
41app's either `++peek` or `++peer` arm. The first response will always be
@@ -51,36 +46,26 @@ either a differntial or full update to the data stream. There may be a
51`%mean`, which indicates that the subscription has been canceled and no
46`%mean`, which indicates that the subscription has been canceled and no
52more responses will be received along this stream.
47more responses will be received along this stream.
53
48
54−------------------------------------------------------------------------
55
49
56−`%nuke`
50+### `%nuke`
57−================
58
51
59Unsubscribes the current duct from its stream. This receives a response
52Unsubscribes the current duct from its stream. This receives a response
60of either a `%nice` or a `%mean`. Note that a response of `%nice` does
53of either a `%nice` or a `%mean`. Note that a response of `%nice` does
61not imply that the current duct was in fact subscribed to any stream.
54not imply that the current duct was in fact subscribed to any stream.
62
55
63−------------------------------------------------------------------------
64−
65−`%init`
56+### `%init`
66−================
67
57
68Initializes a ship's apps. This should be called exactly once for each
58Initializes a ship's apps. This should be called exactly once for each
69ship on the pier. This produces no moves in response.
59ship on the pier. This produces no moves in response.
70
60
71−------------------------------------------------------------------------
72−
73−`%sire`
61+### `%sire`
74−================
75
62
76Instantiates a child app. The app will be at path `[p parent-path]`, and
63Instantiates a child app. The app will be at path `[p parent-path]`, and
77it will be an instance of the `q` app. The only response will be `%gone`
64it will be an instance of the `q` app. The only response will be `%gone`
78when the child dies.
65when the child dies.
79
66
80−------------------------------------------------------------------------
81
67
82−`%rote`
68+### `%rote`
83−================
84
69
85Signifies a remote request from ames. `r` should be of type `rook`. This
70Signifies a remote request from ames. `r` should be of type `rook`. This
86how an app on a foreign ship may send a `%mess`, `%show`, or `%nuke`
71how an app on a foreign ship may send a `%mess`, `%show`, or `%nuke`
@@ -90,10 +75,8 @@ should use `%rote` and `%roth` is ames. Formally, the response is either
90a `%nice` or a `%mean`, which ames uses to give a positive or negative
75a `%nice` or a `%mean`, which ames uses to give a positive or negative
91ack. A logical response comes by passing a `%roth` card.
76ack. A logical response comes by passing a `%roth` card.
92
77
93−------------------------------------------------------------------------
94
78
95−`%roth`
79+### `%roth`
96−================
97
80
98Gives the response received from a remote request. `r` should be of type
81Gives the response received from a remote request. `r` should be of type
99`roon`. This is how an app responds to a foreign request with a `%rush`,
82`roon`. This is how an app responds to a foreign request with a `%rush`,
@@ -102,10 +85,8 @@ Gives the response received from a remote request. `r` should be of type
102need to acknowledge these responses since they're really independent
85need to acknowledge these responses since they're really independent
103one-way messages.
86one-way messages.
104
87
105−------------------------------------------------------------------------
106
88
107−`%wipe`
89+### `%wipe`
108−================
109
90
110Wipes the given app from memory. This is generally considered a hack,
91Wipes the given app from memory. This is generally considered a hack,
111but it is sometimes useful during development to wipe the state of an
92but it is sometimes useful during development to wipe the state of an
@@ -113,10 +94,8 @@ app. We don't guarantee that this actually completely wipes the app.
113Generally, you want to use a `%cide` card if you actually want to kill
94Generally, you want to use a `%cide` card if you actually want to kill
114an app. This gives no response.
95an app. This gives no response.
115
96
116−------------------------------------------------------------------------
117
97
118−`%cide`
98+### `%cide`
119−================
120
99
121Kills an app and all its children. Even though it's not technically a
100Kills an app and all its children. Even though it's not technically a
122part of `%gall`'s interface since it's not in `++kiss` and can't be
101part of `%gall`'s interface since it's not in `++kiss` and can't be
@@ -124,38 +103,30 @@ called from the outside, it's worth mentioning `%cide`, which may be
124called from within `%gall` apps. It should call `++part` to allow the
103called from within `%gall` apps. It should call `++part` to allow the
125app any last words. This gives no response.
104app any last words. This gives no response.
126
105
127−------------------------------------------------------------------------
128−
129Service Gates
106Service Gates
130−=============
107+-------------
131
108
132−[`++poke`]()
109+### `++poke`
133−============
134
110
135Handles incoming messages. Most commonly with an associated `%logo`. For
111Handles incoming messages. Most commonly with an associated `%logo`. For
136example `++poke-json` handles an incoming JSON request from `%eyre`.
112example `++poke-json` handles an incoming JSON request from `%eyre`.
137
113
138−[`++peer`]()
114+### `++peer`
139−============
140
115
141Handles incoming subscriptions.
116Handles incoming subscriptions.
142
117
143−[`++pull`]()
118+### `++pull`
144−============
145
119
146Handles dropping subscribers.
120Handles dropping subscribers.
147
121
148−[`++pour`]()
122+### `++pour`
149−============
150
123
151Handles responses to `%pass` moves.
124Handles responses to `%pass` moves.
152
125
153−[`++park`]()
126+### `++park`
154−============
155
127
156Save state on update.
128Save state on update.
157
129
158−[`++prep`]()
130+### `++prep`
159−============
160
131
161Load state on update.
132Load state on update.
docs/system/hoon.mdnew file+9
@@ -0,0 +1,9 @@
1+---
2+sort: 2
3+---
4+
5+# `hoon`
6+
7+Hoon is our programming language.
8+
9+<list></list>
docs/system/hoon/runes.md−6
@@ -1,5 +1,3 @@
1−<div class="short">
2−
3Runes
1Runes
4=====
2=====
5
3
@@ -12,10 +10,6 @@ find documentation on each individual category, follow these links:
12
10
13<list></list>
11<list></list>
14
12
15−<search/>
16−
17−</div>
18−
19------------------------------------------------------------------------
13------------------------------------------------------------------------
20
14
21Introduction
15Introduction
docs/system/nock.mdnew file+9
@@ -0,0 +1,9 @@
1+---
2+sort: 1
3+---
4+
5+# `nock`
6+
7+Nock is our virtual machine. For an in-depth exploration of Nock, see the [Nock Tutorial](/docs/deep-dives). This reference steps through the requisite definitions and each step of the Nock function.
8+
9+<list></list>