11We've dealt fairly extensively with "poke" messages to an app, but these
12are somewhat limited. A poke is a one-way message, but more often we
13want to subscribe to updates from another app. You could build a
14subscription model out of one-way pokes, but it's such a common pattern
15that it's built into Arvo.
17Let's take a look at two apps, `:source` and `:sink`. First,
21:: Sends subscription updates to sink.hoon
23:::: /===/app/source/hoon
29 +$ card $% [%diff diff-contents]
31+$ diff-contents $% [%noun *]
39 ^- [(list move) _+>.$]
41 %+ turn (prey /example-path bow)
42 |=({o=bone *} [o %diff %noun non])
46 ^- [(list move) _+>.$]
47 ~& source+peer-notify+'Someone subscribed to you!'
48 ~& source+[ship+src.bow path+pax]
52 |= {wir=wire err=(unit tang)}
53 ^- [(list move) _+>.$]
55 ~& source+success+'Poke succeeded!'
57 ~& source+error+'Poke failed. Error:'
62 |= [wir=wire err=(unit tang)]
63 ^- [(list move) _+>.$]
65 ~& source+success+'Peer succeeded!'
67 ~& source+error+'Peer failed. Error:'
77:: Sets up a simple subscription to source.hoon
79:::: /===/app/sink/hoon
84+$ card $% [%peer wire dock path]
89|_ [bow=bowl:gall val=?]
93 ^- [(list move) _+>.$]
103 ?: &(=(%off non) !val)
105 ~[[ost.bow %pull /subscribe [our.bow %source] ~]]
107 sink+unsubscribed+'You are now unsubscribed!'
108 sink+subscribed+'You are now subscribed!'
113 ^- [(list move) _+>.$]
114 ~& sink+received-data+'You got something!'
119 |= [wir=wire err=(unit tang)]
120 ^- [(list move) _+>.$]
122 ~& sink+success+'Poke succeeded!'
124 ~& sink+error+'Poke failed. Error:'
129 |= [wir=wire err=(unit tang)]
130 ^- [(list move) _+>.$]
132 ~& sink+success+'Peer succeeded!'
134 ~& sink+error+'Peer failed. Error:'
143- `bowl` is the type of the system state within our app. For example, it includes things like `our`, the name of the host urbit, and `now`, the current time.
145- You may have noticed the separate `|%` ([barcen](../../hoon/rune/bar/cen/)) above the application core `|_` ([barcab](../../hoon/rune/bar/cab/). We usually put our types in another core on top of the application core. We can access these type from our `|_` because in `hoon.hoon` files, all cores are called against each other. (The shorthand for 'called' is `=>`.) Thus, the `|%` with the types is in the context of the `|_`, as it lies above it: `hoon.hoon` `=> |% w types => |_`
147Here's some sample output of the two working together:
150~fintud-macrep:dojo> |start %source
153~fintud-macrep:dojo> |start %sink
156~fintud-macrep:dojo> :sink %on
157[%source %peer-notify 'Someone subscribed to you!']
158[%source [%ship ~fintud-macrep] %path /]
159[%sink %success 'Peer succeeded!']
162~fintud-macrep:dojo> :source 5
163[%sink %received-data 'You got something!']
167~fintud-macrep:dojo> :sink %off
170~fintud-macrep:dojo> :source 6
173~fintud-macrep:dojo> :sink %on
174[%source %peer-notify 'Someone subscribed to you!']
175[%source [%ship ~fintud-macrep] %path /]
176[%sink %success 'Peer succeeded!']
179~fintud-macrep:dojo> :source 7
180[%sink %received-data 'You got something!']
187Hopefully you can get a sense for what's happening here. When we poke
188`:sink` with `%on`, `:sink` subscribes to `:source`,
189and so whenever we poke `:source`, `:sink` gets the update and
190prints it out. Then we unsubscribe by poking `:sink` with `%off`, and
191`:sink` stops getting updates. We then resubscribe.
193There's a fair bit going on in this code. Let's look at `:source`
196Our definition of `move` is fairly specific, since we're only going to
197sending one kind of move. The `%diff` move is a subscription update, and
198its content is marked data which gall routes to our subscribers.
200This is a slightly different kind of move than we've dealt with so
201far. It's producing a result rather than calling other
202code (i.e. it's a return rather than a function call), so if you recall
203the discussion of ducts, a layer gets popped off the duct rather than
204added to it. This is why no wire is needed for the move -- we won't
205receive anything in response to it.
207Anyways, there are four functions (arms) inside the `|_`. We already know when
208`++poke-noun` is called. `++peer-example-path` is called when someone tries to
209subscribe to our app. Of course, you don't just subscribe to an app; you
210subscribe to a path on that app. This path comes in as the argument to `++peer`.
212In our case, we don't care what path you subscribed on, and all we do is print
213out that you subscribed. Arvo keeps track of your subscriptions, so you don't
214have to. You can access your subscribers by looking at `sup` in the bowl that's
215passed in. `sup` is of type `(map bone {@p path})`, which associates bones with
216the urbit who subscribed, and which path they subscribed on. If you want to
217communicate with your subscribers, send them messages along their bone.
219`++poke-noun` "spams" the given argument to all our subscribers.
220There's a few things we haven't seen before. Firstly, `:_(a b)` is the
221same as `[b a]`. It's just a convenient way of formatting things when
222the first thing in a cell is much more complicated than the second.
223Thus, we're producing our state unchanged.
225Our list of moves is the result of a call to `++turn`. `++turn` is what many
226languages call "map" -- it runs a function on every item in a list and collects
227the results in a list. The list is `(prey /example-path bow)` and the function
228is the `|=` line right after it.
230`++prey` is a standard library function defined in `zuse.hoon`. It takes a path
231and a bowl and gives you a list of the subscribers who are subscribed on a path
232that begins with the given path. "Prey" is short for "prefix".
234Now we have the list of relevant subscribers. This a list of triples,
235`{bone @p path}`, where the only thing we really need is the bone, because we
236don't need to know their urbit or what exact path they subscribed on. Thus, our
237transformer function takes `[o=bone *]` and produces `[o %diff %noun non]`,
238which is a move that provides bone `o` with this subscription update:
239`[%noun non]`". This is fairly dense code, but what it's doing is
244`:source` should now make sense. `:sink` is a little longer, but not much more
247In `:sink`, our definition of of `++move` is different. All moves start
248with a `bone`, and we conventionally refer to the second half as the "card", so
249that we can say a move is an action that sends a card along a bone.
251We have two kinds of cards here: we `%peer` to start a subscription, and we
252`%pull` to stop it. Both of these are "forward" moves that may receive a
253response, so they need a wire to tack onto the duct before they pass it on. They
254also need a target, which is a pair of an urbit and an app name. Additionally,
255`%peer` needs a path on that app to subscribe too. `%pull` doesn't need this,
256because its semantics are to cancel any subscriptions coming over this duct. If
257your bone and wire are the same as when you subscribed, then the cancellation
258will happen correctly.
260The only state we need for `:sink` is a boolean to indicate whether
261we're already subscribed to `:source`. We use `val=?`, where `?`
262is the sign of type boolean (similar to `*`, `@`), which defaults to true (that
265In `++poke-noun` we check our input to see both if it's `%on` and we're
266available (`val` is true). If so, we produce the move to subscribe to
279Also, in the preceding lines, we set `val` to false (`|`) with `+>.$(val |)`.
280Remember that the `:_` constructs an inverted cell, with the first child
281(`+>.$(val |` in our case) as the tail and the second child as the head. Here,
282the cell we produce when our subscription is `%on` and `val` is true has a
283head with our new state where `val` is set to false and a tail of our list of
284moves, which is shown in the code block above.
286Otherwise, if our input is `%off` and we're already subscribed (i.e. `val`
287is false), then we unsubscribe from `:source` and set `val` back to true (`&`),
288again using our handy inverted cell constructor mold `:_`:
292~[[ost.bow %pull /subscribe [our.bow %source] ~]]
295It's important to send over the same bone and wire (`/subscribe`) as the
296one we originally subscribed on.
298If neither of these cases are true, then we print our current subscription
299state, based on whether `val` is true or false, and return a cell containing
300a null list of moves and our unchanged app state:
304 sink+unsubscribed+'You are now unsubscribed!'
305 sink+subscribed+'You are now subscribed!'
309`++diff-noun` is called when we get a `%diff` update along a subscription with a
310mark of `noun`. `++diff-noun` is given the wire that we originally passed with
311the `%peer` subscription request along and the data we got back. In our case we
312just print out the data:
315~& sink+received-data+'You got something!'
319`++reap` is called when we receive an acknowledgment as to whether the
320subscription was handled successfully. You can remember that `++reap` is the
321counterpart to `++peer` as it's pronounced like 'peer' backwards. Similarly,
322`coup` is similar to 'poke' backwards.
324Moving forward, `++reap` is given the wire we attempted to subscribe over,
325possibly along with an error message in cases of failure. `(unit type)` means
326"either `~` or `[~ type]`, which means it's used like Haskell's "maybe" or C's
327nullability. If `err` is `~`, then the subscription was successful and we tell
328that to the user. Otherwise, we print out the error message.
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