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:pubsub:userlib /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:'
74Save this as `source.hoon` in the `/app` directory of your urbit's pier.
79:: Sets up a simple subscription to source.hoon
81:::: /===/app/sink/hoon
86+$ card $% [%peer wire dock path]
91|_ [bow=bowl:gall val=?]
95 ^- [(list move) _+>.$]
105 ?: &(=(%off non) !val)
107 ~[[ost.bow %pull /subscribe [our.bow %source] ~]]
109 sink+unsubscribed+'You are now unsubscribed!'
110 sink+subscribed+'You are now subscribed!'
115 ^- [(list move) _+>.$]
116 ~& sink+received-data+'You got something!'
121 |= [wir=wire err=(unit tang)]
122 ^- [(list move) _+>.$]
124 ~& sink+success+'Poke succeeded!'
126 ~& sink+error+'Poke failed. Error:'
131 |= [wir=wire err=(unit tang)]
132 ^- [(list move) _+>.$]
134 ~& sink+success+'Peer succeeded!'
136 ~& sink+error+'Peer failed. Error:'
143Save this as `sink.hoon` in the `/app` directory of your urbit's pier (make sure both `source` and `sink` are on the same ship).
147- `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.
149- You may have noticed the separate `|%` above the application core `|_`. 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 => |_`
151Here's some sample output of the two working together:
154~fintud-macrep:dojo> |start %source
157~fintud-macrep:dojo> |start %sink
160~fintud-macrep:dojo> :sink %on
161[%source %peer-notify 'Someone subscribed to you!']
162[%source [%ship ~fintud-macrep] %path /]
163[%sink %success 'Peer succeeded!']
166~fintud-macrep:dojo> :source 5
167[%sink %received-data 'You got something!']
171~fintud-macrep:dojo> :sink %off
174~fintud-macrep:dojo> :source 6
177~fintud-macrep:dojo> :sink %on
178[%source %peer-notify 'Someone subscribed to you!']
179[%source [%ship ~fintud-macrep] %path /]
180[%sink %success 'Peer succeeded!']
183~fintud-macrep:dojo> :source 7
184[%sink %received-data 'You got something!']
191Hopefully you can get a sense for what's happening here. When we poke
192`:sink` with `%on`, `:sink` subscribes to `:source`,
193and so whenever we poke `:source`, `:sink` gets the update and
194prints it out. Then we unsubscribe by poking `:sink` with `%off`, and
195`:sink` stops getting updates. We then resubscribe.
197There's a fair bit going on in this code. Let's look at `:source`
200Our definition of `move` is fairly specific, since we're only going to
201sending one kind of move. The `%diff` move is a subscription update, and
202its content is marked data which gall routes to our subscribers.
204This is a slightly different kind of move than we've dealt with so
205far. It's producing a result rather than calling other
206code (i.e. it's a return rather than a function call), so if you recall
207the discussion of ducts, a layer gets popped off the duct rather than
208added to it. This is why no wire is needed for the move -- we won't
209receive anything in response to it.
211Anyways, there are four functions (arms) inside the `|_`. We already know when
212`++poke-noun` is called. `++peer-example-path` is called when someone tries to
213subscribe to our app. Of course, you don't just subscribe to an app; you
214subscribe to a path on that app. This path comes in as the argument to `++peer`.
216In our case, we don't care what path you subscribed on, and all we do is print
217out that you subscribed. Arvo keeps track of your subscriptions, so you don't
218have to. You can access your subscribers by looking at `sup` in the bowl that's
219passed in. `sup` is of type `(map bone {@p path})`, which associates bones with
220the urbit who subscribed, and which path they subscribed on. If you want to
221communicate with your subscribers, send them messages along their bone.
223`++poke-noun` "spams" the given argument to all our subscribers.
224There's a few things we haven't seen before. Firstly, `:_(a b)` is the
225same as `[b a]`. It's just a convenient way of formatting things when
226the first thing in a cell is much more complicated than the second.
227Thus, we're producing our state unchanged.
229Our list of moves is the result of a call to `++turn`. `++turn` is what many
230languages call "map" -- it runs a function on every item in a list and collects
231the results in a list. The list is `(prey /example-path bow)` and the function
232is the `|=` line right after it.
234`prey:pubsub:userlib` is a standard library function defined in `zuse.hoon`. It takes a path
235and a bowl and gives you a list of the subscribers who are subscribed on a path
236that begins with the given path. "Prey" is short for "prefix".
238Now we have the list of relevant subscribers. This a list of triples,
239`[bone @p path]`, where the only thing we really need is the bone, because we
240don't need to know their urbit or what exact path they subscribed on. Thus, our
241transformer function takes `[o=bone *]` and produces `[o %diff %noun non]`,
242which is a move that provides bone `o` with this subscription update:
243`[%noun non]`". This is fairly dense code, but what it's doing is
248`:source` should now make sense. `:sink` is a little longer, but not much more
251In `:sink`, our definition of of `++move` is different. All moves start
252with a `bone`, and we conventionally refer to the second half as the "card", so
253that we can say a move is an action that sends a card along a bone.
255We have two kinds of cards here: we `%peer` to start a subscription, and we
256`%pull` to stop it. Both of these are "forward" moves that may receive a
257response, so they need a wire to tack onto the duct before they pass it on. They
258also need a target, which is a pair of an urbit and an app name. Additionally,
259`%peer` needs a path on that app to subscribe too. `%pull` doesn't need this,
260because its semantics are to cancel any subscriptions coming over this duct. If
261your bone and wire are the same as when you subscribed, then the cancellation
262will happen correctly.
264The only state we need for `:sink` is a boolean to indicate whether
265we're already subscribed to `:source`. We use `val=?`, where `?`
266is the sign of type boolean (similar to `*`, `@`), which defaults to true (that
269In `++poke-noun` we check our input to see both if it's `%on` and we're
270available (`val` is true). If so, we produce the move to subscribe to
283Also, in the preceding lines, we set `val` to false (`|`) with `+>.$(val |)`.
284Remember that the `:_` constructs an inverted cell, with the first child
285(`+>.$(val |` in our case) as the tail and the second child as the head. Here,
286the cell we produce when our subscription is `%on` and `val` is true has a
287head with our new state where `val` is set to false and a tail of our list of
288moves, which is shown in the code block above.
290Otherwise, if our input is `%off` and we're already subscribed (i.e. `val`
291is false), then we unsubscribe from `:source` and set `val` back to true (`&`),
292again using our handy inverted cell constructor mold `:_`:
296~[[ost.bow %pull /subscribe [our.bow %source] ~]]
299It's important to send over the same bone and wire (`/subscribe`) as the
300one we originally subscribed on.
302If neither of these cases are true, then we print our current subscription
303state, based on whether `val` is true or false, and return a cell containing
304a null list of moves and our unchanged app state:
308 sink+unsubscribed+'You are now unsubscribed!'
309 sink+subscribed+'You are now subscribed!'
313`++diff-noun` is called when we get a `%diff` update along a subscription with a
314mark of `noun`. `++diff-noun` is given the wire that we originally passed with
315the `%peer` subscription request along and the data we got back. In our case we
316just print out the data:
319~& sink+received-data+'You got something!'
323`++reap` is called when we receive an acknowledgment as to whether the
324subscription was handled successfully. You can remember that `++reap` is the
325counterpart to `++peer` as it's pronounced like 'peer' backwards. Similarly,
326`coup` is similar to 'poke' backwards.
328Moving forward, `++reap` is given the wire we attempted to subscribe over,
329possibly along with an error message in cases of failure. `(unit type)` means
330"either `~` or `[~ type]`, which means it's used like Haskell's "maybe" or C's
331nullability. If `err` is `~`, then the subscription was successful and we tell
332that 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