git.iko.soy/urbit.org
on 140ac0e help sign in
urbit.org/docs/programming/system/subscriptions.md
279 lines 9.5 kB history raw
1---
2next: true
3sort: 4
4title: Subscriptions
5---
7We've dealt fairly extensively with "poke" messages to an app,
8but these are somewhat limited. A poke is a one-way message, but
9more often we want to subscribe to updates from another app. You
10could build a subscription model out of one-way pokes, but it's
11such a common pattern that it's built into arvo.
13Let's take a look at two apps, `:source` and `:sink`. First,
14`:source`:
16```
17/? 314
18!:
19|%
20++ move ,[bone %diff mark *]
21--
22|_ [hid=bowl state=~]
23++ poke-noun
24 |= arg=*
25 ^- [(list move) _+>.$]
26 :_ +>.$
27 %+ turn (prey /the-path hid)
28 |=([o=bone *] [o %diff %noun arg])
29++ peer
30 |= pax=path
31 ^- [(list move) _+>.$]
32 ~& [%subscribed-to pax=pax]
33 [~ +>.$]
34--
35```
37And secondly, `:sink`:
39```
40/? 314
41|%
42++ move ,[bone card]
43++ card
44 $% [%peer wire [@p term] path]
45 [%pull wire [@p term] ~]
46 ==
47--
48!:
49|_ [bowl available=?]
50++ poke-noun
51 |= arg=*
52 ^- [(list move) _+>.$]
53 ?: &(=(%on arg) available)
54 [[[ost %peer /subscribe [our %source] /the-path] ~] +>.$(available |)]
55 ?: &(=(%off arg) !available)
56 [[[ost %pull /subscribe [our %source] ~] ~] +>.$(available &)]
57 ~& ?:(available %not-subscribed %subscribed)
58 [~ +>.$]
59++ diff-noun
60 |= [wir=wire arg=*]
61 ^- [(list move) _+>.$]
62 ~& [%recieved-data arg]
63 [~ +>.$]
64++ reap
65 |= [wir=wire error=(unit tang)]
66 ^- [(list move) _+>.$]
67 ?~ error
68 ~& %successfully-subscribed
69 [~ +>.$]
70 ~& [%subscription-failed error]
71 [~ +>.$]
72--
73```
75Cheat sheet:
77```
78- `&` can either be the boolean true (along with `%.y`, `0`), or
79 the irregular wide form of the `$&` rune, which computes the
80 logical 'and' operation on its two children.
82- Similar to `&`,`|` is either the boolean false (along with `%.n` and `1`), or
83 the irregular short for of `?|`, which computes the logical 'or' operation on
84 its two children
86- `!` is the irregular wide form of `?!`, which computes the logical `not` on
87 its child.
89- `?~` is basically an if-then-else statement that checks whether condition `p`
90 is `~` (null). `?~` is slightly different to `?:(~ %tru %fal) in that it
91 reduces to ?:($=(%type value) %tru %false). `$=` tests whether value `q`
92 falls within type `p`. One thing to watch out for in hoon: if you do `?~`, it
93 affects the type of the conditional value: XXexample
95- `:_` is just an inverted `:-`: all it does is accept children `p` and `q` and
96 produce an inverted tuple of the two, `[q p]`.
98- `++bowl` is the type of our system state within our app. For example, it
99 includes things like `our`, the ship name of the host, and `now`, the
100 current time.
102- `$%` is a type constructor that defines a type composed of `n`
103 types that it is passed. For example `$% @ * ^ ==` is the
104 type of either `@`, `*`, or a cell `^`. XX this a union, right?
106- You may have noticed the separate `|%` above the application
107 core `|_`. We usually put our types in another core on top of the
108 application core. We can access these type from our `|_`
109 because in hoon.hoon files, all cores are =>'ed (called) against
110 each other. Thus the `|%` with the types is in the context of
111 the `|_`, as it lies above it: hoon.hoon `=> |% w types =>
112 |_`
117```
119Here's some sample output of the two working together:
121```
122~fintud-macrep:dojo> |start %source
123>=
124~fintud-macrep:dojo> |start %sink
125>=
126~fintud-macrep:dojo> :sink %on
127[%subscribed-to pax=/the-path]
128%successfully-subscribed]
129>=
130~fintud-macrep:dojo> :source 5
131[%received-data 5]
132>=
133~fintud-macrep:dojo> :sink %off
134>=
135~fintud-macrep:dojo> :source 6
136>=
137~fintud-macrep:dojo> :sink %on
138[%subscribed-to pax=/the-path]
139%successfully-subscribed]
140>=
141~fintud-macrep:dojo> :source 7
142[%received-data 7]
143>=
144```
146###:source
148Hopefully you can get a sense for what's happening here. When we
149poke `:sink` with `%on`, `:sink` subscribes to `:source`, and so
150whenever we poke `:source`, `:sink` gets the update and prints it
151out. Then we unsubscribe by poking `:sink` with `%off`, and
152`:sink` stops getting updates. We then resubscribe.
154There's a fair bit going on in this code, Let's look at
155`:source` first.
157Our definition of `move` is fairly specific, since we're only
158going to sending one kind of move. The `%diff` move is a
159subscription update, and its content is marked data which gall
160routes to our subscribers.
162This is a slightly different kind of move than we've dealt with
163so far. It's producing a result rather than calling other code
164(i.e. it's a return rather than a function call), so if you
165recall the discussion of ducts, a layer gets popped off the duct
166rather than added to it. This is why no wire is needed for the
167move -- we won't receive anything in response to it.
169Anyways, there're two functions inside the `|_`. We already know
170when `++poke-noun` is called. `++peer` is called when someone
171tries to subscribe to our app. Of course, you don't just
172subscribe to an app; you subscribe to a path on that app. This
173path comes in as the argument to `++peer`.
175In our case, we don't care what path you subscribed on, and all
176we do is print out that you subscribed. Arvo keeps track of your
177subscriptions, so you don't have to. You can access your
178subscribers by looking at `sup` in the bowl that's passed in.
179`sup` is of type `(map bone ,[@p path])`, which associates bones
180with the urbit who subscribed, and which path they subscribed on.
181If you want to talk to your subscribers, send them messages along
182their bone.
184`++poke-noun` spams the given arguement to all our subscribers.
185There's a few things we haven't seen before. Firstly, `:_(a b)`
186is the same as `[b a]`. It's just a convenient way of formatting
187things when the first thing in a cell is much more complicated
188than the second. Thus, we're producing our state unchanged.
190Our list of moves is the result of a call to `++turn`. `++turn`
191is what many languages call "map" -- it runs a function on every
192item in a list and collects the results in a list. The list is
193`(prey /the-path hid)` and the function is the `|=` line right
194after it.
196`++prey` is a standard library function defined in `zuse`. It
197takes a path and a bowl and gives you a list of the subscribers
198who are subscribed on a path that begins with the given path.
199"Prey" is short for "prefix".
201Now we have the list of relevant subscribers. This a list of
202triples, `[bone @p path]`, where the only thing we really need is
203the bone because we don't care what urbit they are or what exact
204path they subscribed on. Thus, our transformer function takes
205`[o=bone *]` and produces `[o %diff %noun arg]`, which is a move
206that means "tell bone `o` this subscription update: `[%noun
207arg]`". This is fairly dense code, but what it's doing is
208straightforward.
210###:sink
212`:source` should now make sense. `:sink` is a little longer,
213but not much more complicated.
215In `:sink`, our definition of of `++move` is different. All
216moves start with a `bone`, and we conventionally refer to the
217second half as the "card", so that we can say a move is an action
218that sends a card along a bone.
220We have two kinds of cards here: we `%peer` to start a
221subscription, and we `%pull` to stop it. Both of these are
222"forward" moves that may receive a response, so they need a wire
223to tack onto the duct before they pass it on. They also need a
224target, which is a pair of an urbit and an app name. Additionally, `%peer`
225needs a path on that app to subscribe too. `%pull` doesn't need
226this, because its semantics are to cancel any subscriptions
227coming over this duct. If your bone and wire are the same as
228when you subscribed, then the cancellation will happen correctly.
230The only state we need for `:sink` is a loobean to tell whether
231we're already subscribed to `:source`. We use `available=?`,
232where `?` is the sign of type boolean (similar to `*`, `@`) (which defaults to true).
234In `++poke-noun` we check our input to see both if it's `%on` and
235we're available. If so, we produce the move to subscribe to
236`:source`:
238```
239[ost %peer /subscribe [our %source] /the-path]
240```
242Also, we set available to false (`|`) with `+>.$(available |)`.
244Otherwise, if our input is `%off` and we're already subscribed
245(i.e. `available` is false), then we unsubscribe from
246`:source`:
248```
249[ost %pull /subscribe [our %source] ~]
250```
252It's important to send over the same bone and wire (`/subscribe`)
253as the one we originally subscribed on.
255We also set `available` to true (`&`).
257If neither of these cases are true, then we just print out our
258current subscription state and do nothing.
260`++diff-noun` is called when we get a `%diff` update along a
261subscription with a mark of `noun`. `++diff-noun` is given the
262wire that we originally passed with the `%peer` subscription
263request along and the data we got back. In our case we just
264print out the data.
266`++reap` is called when we receive an acknowledgment as to
267whether the subscription was handled successfully. You can
268remember that `++reap` is the counterpart to `++peer` as it's
269almost spelled the same as 'peer' backwards. Similarly, `coup` is
270similar to 'poke' backwards.
272Moving forward, `++reap` is given the wire we attempted to
273subscribe over, possibly along with an error message in cases of
274failure. `(unit type)` means "either `~` or `[~ type]`, which
275means it's used like Haskell's "maybe" or C's nullability. If
276`error` is `~`, then the subscription was successful, so we tell
277that to the user. Otherwise, we print out the error message.
279Excercises XX