6. Pokes
In this lesson we'll look at sending and receiving one-off messages called %pokes. We'll look at the +on-poke agent arm which handles incoming pokes. We'll also introduce the +on-agent arm, and look at the one kind of response it can take - a %poke-ack.
Receiving a poke
Whenever something tries to poke your agent, Gall calls your agent's +on-poke arm and give it the $cage from the poke as its sample. The +on-poke arm will produce a (quip card _this). Here's how it would typically begin:
++ on-poke
|= [=mark =vase]
^- (quip card _this)
...The sample of the gate is usually specified as a cell of $mark and $vase rather than just $cage, simply because it's easier to work with.
Typically, you'd first test the $mark with something like a wutlus ?+ expression, passing unexpected $marks to default-agent, which just crashes. We'll look at custom $marks in a subsequent lesson, but the basic pattern looks like:
?+ mark (on-poke:def mark vase)
%noun ...
%something-else ...
...
==After testing the $mark, you'd usually extract the $vase to the expected type, and then apply whatever logic you need. For example:
=/ action !<(some-type vase)
?- -.action
%foo ...
%bar ...
...
==Your agent will then produce a list of $cards to be sent off and a new, modified state, as appropriate. We'll go into subscriptions in the next lesson, but just to give you an idea of a typical pattern: An agent for a chat app might take new messages as pokes, add them to the list of messages in its state, and send out the new messages to subscribed chat participants as gifts.
As discussed in the previous lesson, Gall will automatically send a %poke-ack gift back to wherever the poke came from. The %poke-ack will be a nack if your agent crashed while processing the poke, and an ack otherwise. If it's a nack, the $tang in the %poke-ack will contain a stack trace of the crash.
As a result, you do not need to explicitly send a %poke-ack. Instead, you would design your agent to handle only what you expect and crash in all other cases. You can crash by passing the $cage to default-agent, or just with a !!. In the latter case, if you want to add an error message to the stack trace, you can do so like:
~| "some error message"
!!This will produce a trace that looks something like:
/sys/vane/gall/hoon:<[1.372 9].[1.372 37]>
/app/pokeme/hoon:<[31 3].[43 5]>
/app/pokeme/hoon:<[32 3].[43 5]>
/app/pokeme/hoon:<[34 5].[42 7]>
/app/pokeme/hoon:<[35 5].[42 7]>
/app/pokeme/hoon:<[38 7].[41 27]>
/app/pokeme/hoon:<[39 9].[40 11]>
"some error message"
/app/pokeme/hoon:<[40 9].[40 11]>Note that the $tang in the nack is just for debugging purposes, you should not try to pass actual data by encoding it in the nack $tang.
Sending a poke
An agent can send pokes to other agents by producing %poke $cards. Any agent arm apart from +on-peek and +on-save can produce such $cards. The arms would typically produce the (quip card _this) like so:
:_ this
:~ [%pass /some/wire %agent [~target-ship %target-agent] %poke %some-mark !>('some data')]
==The colcab (:_) rune makes an inverted cell, it's just :- but with the head and tail swapped. We use colcab to produce the (quip card _this) because the list of cards is "heavier" here than the new agent core expression (.this), so it makes it more readable.
Receiving the %poke-ack
%poke-ackThe pokes will be processed by their targets as described in the previous section, and they'll %give back a %poke-ack on the $wire you specified (/some/wire in the previous example). When Gall gets the %poke-ack back, it will call the +on-agent arm of your agent, with the $wire it came in on and the %poke-ack itself in a sign:agent:gall. Your +on-agent arm would therefore begin like so:
++ on-agent
|= [=wire =sign:agent:gall]
^- (quip card _this)
...A $sign:agent:gall (henceforth just $sign) is defined in /sys/lull.hoon as:
+$ sign
$% [%poke-ack p=(unit tang)]
[%watch-ack p=(unit tang)]
[%fact =cage]
[%kick ~]
==It's basically the same as a gift, but incoming instead of outgoing.
The simplest way to handle a %poke-ack by passing it to default-agent's +on-agent arm, which will just print an error message to the terminal if it's a nack, and otherwise do nothing. Sometimes you'll want your agent to do something different depending on whether the poke failed or succeeded (and therefore whether it's a nack or an ack).
You should always route on wire before sign, never sign before wire. You might do something like:
?+ wire (on-agent:def wire sign)
[%some %wire ~] ...
...
==After that, you'll need to see what kind of $sign it is:
?+ -.sign (on-agent:def wire sign)
%poke-ack ...
...Then, you can tell whether it's an ack or a nack by testing whether the (unit tang) in the %poke-ack is null:
?~ p.sign
...(what to do if the poke succeeded)...
...(what to do if the poke failed)...Finally, you can produce the (quip card _this).
Example
We're going to look at a couple of agents to demonstrate both sending and receiving pokes. Here's the first, an agent that receives pokes:
This is a very simple agent that just has .val, a number, in its state. It will take pokes that either increment or decrement .val. Here's its +on-poke arm:
++ on-poke
|= [=mark =vase]
^- (quip card _this)
?+ mark (on-poke:def mark vase)
%noun
=/ action !<(?(%inc %dec) vase)
?- action
%inc `this(val +(val))
%dec
?: =(0 val)
~| "Can't decrement - already zero!"
!!
`this(val (dec val))
==
==It only expects pokes with a %noun mark, and passes all others to +on-poke:def, which just crashes. For %noun pokes, it expects to receive either %inc or %dec in the $vase. If it's %inc, it produces a new .this with .val incremented. If it's %dec, it produces .this with .val decremented, or crashes if .val is already zero.
Let's try it out. Save the agent above as /app/pokeme.hoon in the %base desk and |commit %base. Then, start it up with |rein %base [& %pokeme]. We can check its initial state with +dbug:
> 0
> :pokeme +dbug [%state %val]
>=Next, we'll try poking it. The Dojo lets you poke agents with the following syntax:
:agent-name &some-mark ['some' 'noun']If the $mark part is omitted, it'll just default to %noun. Since our agent only takes a %noun mark, we can skip that. The rest will be packed in a $vase by the Dojo and delivered as a poke, so we can do:
> :pokeme %inc
>=If we now look at the state with +dbug, we'll see the poke was successful and it's been incremented:
> 1
> :pokeme +dbug [%state %val]
>=Let's try decrement:
> :pokeme %dec
>=
> 0
> :pokeme +dbug [%state %val]
>=As you can see, it's back at zero. If we try again, we'll see it fails, and the Dojo will print the $tang in the %poke-ack nack:
> :pokeme %dec
/sys/vane/gall/hoon:<[1.828 9].[1.828 37]>
/app/pokeme/hoon:<[35 3].[48 5]>
/app/pokeme/hoon:<[36 3].[48 5]>
/app/pokeme/hoon:<[38 5].[47 7]>
/app/pokeme/hoon:<[39 5].[47 7]>
/app/pokeme/hoon:<[43 7].[46 27]>
/app/pokeme/hoon:<[44 9].[45 11]>
"Can't decrement - already zero!"
/app/pokeme/hoon:<[45 9].[45 11]>
dojo: app poke failedHere's a second agent. It takes a poke of %inc or %dec like before, but rather than updating its own state, it sends two pokes to %pokeme, so %pokeme's state will be incremented or decremented by two.
Here's the +on-poke arm:
++ on-poke
|= [=mark =vase]
^- (quip card _this)
?+ mark (on-poke:def mark vase)
%noun
=/ action !<(?(%inc %dec) vase)
?- action
%inc
:_ this
:~ [%pass /inc %agent [our.bowl %pokeme] %poke %noun !>(%inc)]
[%pass /inc %agent [our.bowl %pokeme] %poke %noun !>(%inc)]
==
%dec
:_ this
:~ [%pass /dec %agent [our.bowl %pokeme] %poke %noun !>(%dec)]
[%pass /dec %agent [our.bowl %pokeme] %poke %noun !>(%dec)]
==
==
==It's similar to %pokeme, except it sends two %poke $cards to %pokeme for each case, rather than modifying its own state. The %inc pokes specify a $wire of /inc, and the %dec pokes specify a $wire of /dec, so we can differentiate the responses. It also has the following +on-agent:
++ on-agent
|= [=wire =sign:agent:gall]
^- (quip card _this)
?+ wire (on-agent wire sign)
[%inc ~]
?. ?=(%poke-ack -.sign)
(on-agent wire sign)
?~ p.sign
%- (slog '%pokeit: Increment poke succeeded!' ~)
`this
%- (slog '%pokeit: Increment poke failed!' ~)
`this
::
[%dec ~]
?. ?=(%poke-ack -.sign)
(on-agent wire sign)
?~ p.sign
%- (slog '%pokeit: Decrement poke succeeded!' ~)
`this
%- (slog '%pokeit: Decrement poke failed!' ~)
`this
==+on-agent tests the $wire, checks if it's a %poke-ack, and then prints to the terminal whether it succeeded or failed.
Save this agent to /app/pokeit.hoon on the %base desk, |commit %base, and start it with |rein %base [& %pokeme] [& %pokeit].
Let's try it out:
%pokeit: Increment poke succeeded!
%pokeit: Increment poke succeeded!
> :pokeit %inc
>=%pokeit has received positive %poke-acks, which means both pokes succeeded. It could tell they were increments because the %poke-acks came back on the /inc wire we specified. We can check the state of %pokeme to confirm:
> 2
> :pokeme +dbug [%state %val]
>=Let's try decrementing %pokeme so val is 1, and then try a %dec via %pokeit:
> :pokeme %dec
>=
%pokeit: Decrement poke succeeded!
%pokeit: Decrement poke failed!
> :pokeit %dec
>=The +on-agent arm of %pokeit has received one ack and one nack. The first took .val to zero, and the second crashed trying to decrement below zero.
Summary
Incoming pokes go to the
+on-pokearm of an agent.The
+on-pokearm takes a$cageand produces an(quip card _this).Gall will automatically return a
%poke-ackto the poke's source, with a stack trace in the(unit tang)if your agent crashed while processing the poke.Outgoing pokes can be sent by including
%poke%pass$cards in the+quipproduced by most agent arms.%poke-acks in response to pokes you've sent will come in to the+on-agentarm in a$sign, on the$wireyou specified in the original%poke$card.You can poke agents from the Dojo with a syntax of
:agent &mark ['some' 'noun'].
Exercises
Run through the example yourself on a fake ship if you've not done so already.
Have a look at the
+on-agentarm of/lib/default-agent.hoonto see how default-agent handles incoming$signs.Try modifying the
%pokemeagent with another action of your choice (in addition to%incand%dec).Try modifying the
%pokeitagent to send your new type of poke to%pokeme, and handle the%poke-ackit gets back.
Last updated