@@ -5,6 +5,8 @@ sort: 5
5title: Subscriptions
5title: Subscriptions
8We've dealt fairly extensively with "poke" messages to an app,
10We've dealt fairly extensively with "poke" messages to an app,
9but these are somewhat limited. A poke is a one-way message, but
11but these are somewhat limited. A poke is a one-way message, but
10more often we want to subscribe to updates from another app. You
12more often we want to subscribe to updates from another app. You
@@ -75,49 +77,48 @@ And secondly, `:examples-sink`:
76Cheat sheet:
78Cheat sheet:
79−- `&` can either be the boolean true (along with `%.y`, `0`), or
80+- `&` (pam) can either be the boolean true (along with `%.y`, `0`), or
80− the irregular wide form of the `$&` rune, which computes the
81+ the irregular wide form of the `?&` ([wutpam](/hoon/twig/wut-test/pam-and)) rune, which computes the
81− logical 'and' operation on its two children.
82+ logical `AND` operation on its two children.
83- Similar to `&`,`|` is either the boolean false (along with `%.n` and `1`), or
84- Similar to `&`,`|` is either the boolean false (along with `%.n` and `1`), or
84− the irregular short for of `?|`, which computes the logical 'or' operation on
85+ the irregular short for of `?|` ([wutbar](/hoon/twig/wut-test/bar-or)), which computes logical `OR` on
85− its two children
86+ its two children.
87−- `!` is the irregular wide form of `?!`, which computes the logical `not` on
88+- `!` is the irregular wide form of `?!` ([wutzap](/hoon/twig/wut-test/zap-not/)), which computes
88− its child.
89+ logical `NOT` on its child.
90−- `?~` is basically an if-then-else statement that checks whether condition `p`
91+- `?~` ([wutsig](/hoon/twig/wut-test/sig-ifno/)) is basically an if-then-else that checks whether condition `p`
91− is `~` (null). `?~` is slightly different to `?:(~ %tru %fal) in that it
92+ is `~` (null). `?~` is slightly different from `?:(~ %tru %fal)` in that `?~`
92− reduces to ?:($=(%type value) %tru %false). `$=` tests whether value `q`
93+ reduces to `?:($=(%type value) %tru %false)`. `$=` ([buctis](/hoon/twig/buc-mold/tis-coat/)) tests whether
94+ value `q` is of type `p`.
93− falls within type `p`. One thing to watch out for in hoon: if you do `?~`, it
95+ <!--One thing to watch out for in hoon: if you do `?~`, it
94− affects the type of the conditional value: XXexample
96+ affects the type of the conditional value: XXexample-->
96−- `:_` is just an inverted `:-`: all it does is accept children `p` and `q` and
98+- `:_` ([colcab](/hoon/twig/col-cell/cab-scon/)) is inverted `:-`: it accepts `p` and `q`, and produces `[q p]`.
97− produce an inverted tuple of the two, `[q p]`.
99−- `++bowl` is the type of our system state within our app. For example, it
100+- `++bowl` is the type of the system state within our app. For example, it
100− includes things like `our`, the ship name of the host, and `now`, the
101+ includes things like `our`, the name of the host urbit, and `now`, the
101 current time.
102 current time.
103−- `$%` is a type constructor that defines a type composed of `n`
104+- `$%` ([buccen](/hoon/twig/buc-mold/cen-book/)) is a type constructor: it defines a new type, composed of `n`
104 types that it is passed. For example `$% @ * ^ ==` is the
105 types that it is passed. For example `$% @ * ^ ==` is the
105− type of either `@`, `*`, or a cell `^`. XX this a union, right?
106+ type of either `@`, `*`, or a cell `^`. <!--XX this is a union, right?-->
107−- You may have noticed the separate `|%` above the application
108+- You may have noticed the separate `|%` ([barcen](/hoon/twig/bar-core/cen-core/)) above the application
108− core `|_`. We usually put our types in another core on top of the
109+ core `|_` ([barcab](/hoon/twig/bar-core/cab-door/). We usually put our types in another core on top of the
109 application core. We can access these type from our `|_`
110 application core. We can access these type from our `|_`
110− because in hoon.hoon files, all cores are =>'ed (called) against
111+ because in `hoon.hoon` files, all cores are called against
112+ each other. (The shorthand for 'called' is `=>`.) Thus, the
111− each other. Thus the `|%` with the types is in the context of
113+ `|%` with the types is in the context of the `|_`, as it lies
112− the `|_`, as it lies above it: hoon.hoon `=> |% w types =>
114+ above it: `hoon.hoon` `=> |% w types =>
118Here's some sample output of the two working together:
118Here's some sample output of the two working together:
121~fintud-macrep:dojo> |start %examples-source
122~fintud-macrep:dojo> |start %examples-source
123~fintud-macrep:dojo> |start %examples-sink
124~fintud-macrep:dojo> |start %examples-sink
@@ -140,6 +141,7 @@ Here's some sample output of the two working together:
140~fintud-macrep:dojo> :examples-source 7
141~fintud-macrep:dojo> :examples-source 7
141[%received-data 7]
142[%received-data 7]
145###:examples-source
147###:examples-source
@@ -158,8 +160,8 @@ going to sending one kind of move. The `%diff` move is a
158subscription update, and its content is marked data which gall
160subscription update, and its content is marked data which gall
159routes to our subscribers.
161routes to our subscribers.
161−This is a slightly different kind of move than we've dealt with
163+This is a slightly different kind of move than [we've dealt with
162−so far. It's producing a result rather than calling other code
164+so far](/arvo/network). It's producing a result rather than calling other code
163(i.e. it's a return rather than a function call), so if you
165(i.e. it's a return rather than a function call), so if you
164recall the discussion of ducts, a layer gets popped off the duct
166recall the discussion of ducts, a layer gets popped off the duct
165rather than added to it. This is why no wire is needed for the
167rather than added to it. This is why no wire is needed for the
@@ -199,7 +201,7 @@ who are subscribed on a path that begins with the given path.
200Now we have the list of relevant subscribers. This a list of
202Now we have the list of relevant subscribers. This a list of
201triples, `{bone @p path}`, where the only thing we really need is
203triples, `{bone @p path}`, where the only thing we really need is
202−the bone because we don't care what urbit they are or what exact
204+the bone, because we don't need to know their urbit or what exact
203path they subscribed on. Thus, our transformer function takes
205path they subscribed on. Thus, our transformer function takes
204`{o/bone *}` and produces `[o %diff %noun arg]`, which is a move
206`{o/bone *}` and produces `[o %diff %noun arg]`, which is a move
205that provides bone `o` with this subscription update: `[%noun
207that provides bone `o` with this subscription update: `[%noun
@@ -228,7 +230,7 @@ when you subscribed, then the cancellation will happen correctly.
229The only state we need for `:examples-sink` is a boolean to indicate whether
231The only state we need for `:examples-sink` is a boolean to indicate whether
230we're already subscribed to `:examples-source`. We use `available/?`,
232we're already subscribed to `:examples-source`. We use `available/?`,
231−where `?` is the sign of type boolean (similar to `*`, `@`) (which defaults to true).
233+where `?` is the sign of type boolean (similar to `*`, `@`), which defaults to true (that is, `0`).
233In `++poke-noun` we check our input to see both if it's `%on` and
235In `++poke-noun` we check our input to see both if it's `%on` and
234we're available. If so, we produce the move to subscribe to
236we're available. If so, we produce the move to subscribe to
@@ -253,8 +255,8 @@ as the one we originally subscribed on.
254We also set `available` to true (`&`).
256We also set `available` to true (`&`).
256−If neither of these cases are true, then we just print out our
258+If neither of these cases are true, then we print our
257−current subscription state and do nothing.
259+current subscription state.
259`++diff-noun` is called when we get a `%diff` update along a
261`++diff-noun` is called when we get a `%diff` update along a
260subscription with a mark of `noun`. `++diff-noun` is given the
262subscription with a mark of `noun`. `++diff-noun` is given the
@@ -265,7 +267,7 @@ print out the data.
265`++reap` is called when we receive an acknowledgment as to
267`++reap` is called when we receive an acknowledgment as to
266whether the subscription was handled successfully. You can
268whether the subscription was handled successfully. You can
267remember that `++reap` is the counterpart to `++peer` as it's
269remember that `++reap` is the counterpart to `++peer` as it's
268−almost spelled the same as 'peer' backwards. Similarly, `coup` is
270+pronounced like 'peer' backwards. Similarly, `coup` is
269similar to 'poke' backwards.
271similar to 'poke' backwards.
271Moving forward, `++reap` is given the wire we attempted to
273Moving forward, `++reap` is given the wire we attempted to