7Now we've learned enough hoon to do more interesting things.
8Let's get our planets to talk to each other.
10All we've written up until now are just shell
11commands that produce a value and then disappear. We need an
12actual app to listen for messages from another planet. Let's
13take a look at a very basic app that does this.
16:: There is no love that is not an echo
32This is a very simple app that does only one thing. If you poke
33it with a value, it prints that value out. To try this out, you
34have to start the app, then you can poke it from the command line
35with the following commands:
38~fintud-macrep:dojo> |start %echo
40~fintud-macrep:dojo> :echo 5
43~fintud-macrep:dojo> :echo [1 2]
48> There is currently a bug where the `%argument` lines are
49> printed *above* the line you entered, so your output may not
50> look exactly like this.
51> `>=` means that a command was successfully received and
54Most of the app code should be simple enough to guess its
55function. The important part of this code is the definition of
58Once an app starts, it's always running in the background and you
59interact with it by sending it messages. The most
60straightforward way to do that is to poke it from the command
61line, which we we did with `:echo 5` (`:[app-name]
64In this case, `++poke-noun` takes an argument `arg` and prints it
65out with `~&`. This is an unusual rune that formally "does
66nothing", but the interpreter detects it and printfs the first
67child, before executing the second as if the first didn't exist.
68This is a slightly hacky way of printing to the console, but
69we'll get to the correct way later on.
71But what does `++poke-noun` produce? Recall that `^-` casts to a
72type. In this case, it's declaring that end result of the
73function will be of type `[(list) _+>.$]`. But what does this
76The phrase to remember is "a list of moves and our state". Urbit
77is a message passing system XX should we mention event
78driven operating system XX, so whenever we want to do something that
79interacts with the rest of the system we send a message. Thus, a
80move is arvo's equivalent of a syscall. The first thing that
81`++poke-noun` produces is a list of messages, called
82"moves". In this case, we don't actually want the system to do
83anything, so we produce the empty list, `~` (in the `[~ +>.$]`
86The second thing `++poke-noun` produces is our state. `+>.$`
87refers to a particular address in our subject where our formal
88app state is stored. It'll become clear why this is later on,
89but for now pretend that `+>.$` is a magic invocation that means
92Let's look at another example. Say we want to only accept a
93number, and then print out the square of that number.
103 ~& [%square (mul arg arg)]
108A few things have changed. Firstly, we no longer accept
109arbitrary nouns because we can only square atoms (integers, in
110this case an unsigned one). Thus, our argument is now `arg=@`.
111Secondly, it's `++poke-atom` rather than `++poke-noun`.
113Are there other `++poke`s? Yes. In fact, `noun` and
114`atom` are just two of arbitrarily many "marks". A mark is
115fundamentally a type definition, but accessible at the arvo
116level. Each mark is defined in the `/mar` directory. Some marks
117have conversion routines to other marks, and some have diff,
118patch, and merge algorithms. None of these are required for a
119mark to exist, however.
121`noun` and `atom` are two of dozens of predefined marks (that will
122already be in your `/mar` directory), and the
123user may add more at will. The type associated with `noun` is
124`*`, and the type associated with `atom` is `@`.
126When we poke an app from anywhere, we do so with a mark that
127searches for the corresponding (`++poke-[mark]`) arm. Data
128constructed on the command line is by default marked with `noun`.
129In this case, the app is expecting an atom, so we have to
130explicitly mark the data with `atom` using `&[mark]`. Try the following
134~fintud-macrep:dojo> |start %square
136~fintud-macrep:dojo> :square 6
137gall: %square: no poke arm for noun
138~fintud-macrep:dojo> :square &atom 6
143> Recall the bug where `%square` may get printed above the input
146Marks are powerful, and they're the backbone of urbit's data
147pipeline, so we'll be getting quite used to them.
151- Write an app that computes fizzbuzz on its input (as in the
154- One way of representing strings is with double quoted strings
155 called "tapes". The hoon type is `++tape`, and there is a
156 corresponding mark with the same name. Write an app that
157 accepts a tape and prints out `(flop argument)`, where
158 `argument` is the input. What does this do?
161Let's write our first network message! Here's `/ape/pong.hoon`:
166 ++ move ,[bone term wire *]
173 ^- [(list move) _+>.$]
174 [[[ost %poke /sending [to %pong] %atom 'howdy'] ~] +>.$]
178 ^- [(list move) _+>.$]
179 ~& [%receiving (,@t arg)]
182++ coup |=(* [~ +>.$])
186Run it with these commands:
189~fintud-macrep:dojo> |start %pong
191~fintud-macrep:dojo> :pong &urbit ~sampel-sipnym
195Replace `~sampel-sipnym` with another urbit. The easiest thing to
196do is to start a [moon](), a sub-identity of your urbit. Don't
197forget to start the `%pong` app on that urbit too. You should
198see, on the foreign urbit, this output:
204Most of the code should be straightforward. In `++poke-atom`,
205the only new thing is the expression `(,@t arg)`. As we already
206know, `@t` is the type of "cord" text strings. `,` is the
207irregular short form of `$,`an operator that turns a type into a
208validator function (called a "clam" in hoon) -- that is, a
209function whose domain is all nouns and range is the given type.
210In simpler terms, if a validator function is passed a value that
211falls within its type, that value is produced. Otherwise, it
212produces the default value (aka the "bunt") of its type. Here we call
213this `,@t` function on the argument. This coerces the argument
214to text, so that we can print it out prettily no matter what
217The more interesting part is in `++poke-urbit`. The `urbit` mark
218is an urbit identity, and the hoon type associated with it is
219`@p` (the "p" stands for "phonetic base").
221Recall that in a `++poke` arm we produce "a list of moves and our
222state". Until now, we've left the list of moves empty, since we
223haven't wanted to tell arvo to do anything in particular. Now we
224want to send a message to another urbit. Thus, we produce a list
228[ost %poke /sending [to-urbit-address %pong] %atom 'howdy']
232The general form of a move is
234 >-app/vane-specific part of move
241`["cause" sys-call/action tack-new-layer-on-cause action-specific
244Let's walk through each of these elements step by step
248If you look up `++bone` in `hoon.hoon`, you'll see that it's a
249number (`@ud`), and that it's an opaque reference to a duct.
250`++duct` in hoon.hoon is a list of `wire`s, where `wire` is an
251alias for `path`. `++path` is a list of `span`s, which are ASCII
252text. Thus, a duct is a list of paths, and a bone is an opaque
253reference to it (in the same way that a Unix file
254descriptor is an opaque reference to a file structure). Thus, to
255truly understand bones, we must understand ducts.
257A duct is stack of causes, again, represented as paths, which are
258called wires. At the bottom of every duct is a unix event, such
259as a keystroke, network packet, file change, or timer event.
260When arvo is given this event, it routes the event to appropriate
261kernel module for handling.
263XX[short explanation of the composition of arvo should be here.]
265Sometimes, the module can immediately handle the event and
266produce any necessary results. For example, when we poked the
267`++poke-atom` arm above, we poked %gall, our application server,
268which was able to respond to our poke directly. When the module
269cannot service the request itself, it sends instructions to the other kernel
270module or application to do a specified action, and produces the
271result from that. Furthermore, when one module sends a message to another kernel
272module or application, it also sends along the duct it was given
273with its new wire tacked onto the end. Now the duct has two entries,
274with the unix even on the bottom and the kernel module that
275handled it next. This process can continue indefinitely, adding
276more and more layers onto the duct. When an entity finally
277produces a result, a layer is popped off the duct, and the result
278is passed all the way back down.
280In effect, a duct is an arvo-level call stack. It's worth noting
281that while in traditional call stacks a function call happens
282synchronously and returns exactly once. In arvo, multiple moves
283can be sent at once, are evaluated asynchronously, and each
284one may be responded to zero or more times.
286The point to take home is that whatever caused `++poke-urbit` to be
287called is also the root cause for the network message we're
288trying to send. Thus, we say to send the network message along the given bone
291#####Wire ('tack on new layer to duct')
293Of course, we have to push a new layer onto our duct
294before passing it along (or responding to it directly) anywhere This
295layer can have any data we want in it, but we don't need anything
296specific here, so we just use the wire `/sending`
297(`/elem1/elem2/elem n` is one syntax used to create `++path`s and
298`++wire`s of n elements). If we were expecting a response (which
299we're not), it would come back along the `/sending` wire, meaning
300that the path `/sending` will be passed back to the response
301handler as an argument. Although it's not required, it's
302generally a good idea to make the wire human-readable for
303bug-handling purposes.
307Looking back at the general form of a move, there is a
308`term`--which is text composed lowercase ascii and `-`, and has
309the sign of `@tas`-- which in this case is `%poke`. This is the
310name of the particular kind of move we're sending. If you think
311of a move as a syscall (which you should), then this `term` is
312the name of the syscall. Common ones include: `%poke`, to
313message an app; `%warp`, to read from the filesystem; `%wait`, to
314set a timer; and `%them`, to send an http request.
316XXDescribe where they can find a list of these things.
318The general form ends with `*` (a noun) since each type of move takes
319different data. In our case, a `%poke` move takes a target
320(urbit and app) and marked data and pokes the arm of the
321corresponding mark on that app on that urbit
322with that data. `[to-urbit-address %pong]` is the target urbit and app,
323`%atom` is the mark`, and `'howdy'` is the data.
325When arvo receives a `%poke` move, it calls the appropriate
326`++poke`. The same mechanism is used for sending messages
327between apps on the same urbit as for sending messages between
328apps on different urbits.
330> We said earlier that we're not expecting a response. This is
331> not entirely true: the `++coup` is called when we receive
332> acknowledgment that the `++poke` was called. We don't do
333> anything with this information right now, but we could.
337- Extend either of the apps in the first two exercises to accept
338 input over the network in the same way as `pong`.
340- Modify `pong` to print out a message when it receives an ack.
342- Write two apps, `even` and `odd`. When you pass an atom to
343 `even`, check whether it's even. If so, divide it by two and
344 recurse; otherwise, poke `odd` with it. When `odd` recieves
345 an atom, check whether it's equal to one. If so, terminate,
346 printing "%success". Otherwise, check whether it's odd. If
347 so, multiply it by three, add one, and recurse; otherwise, poke
348 `even` with it. multiply it by three and add one. When either
349 app receives a number, print it out along with the name of the
350 app. In the end, you should be able to watch Collatz's
351 conjecture play out between the two apps. Sample output:
354~fintud-macrep:dojo> :even &atom 18
378- Put `even` and `odd` on two separate ships and pass the
379 messages over the network.
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