In the last lesson we looked at a couple of useful things used as boilerplate in
most agents. Now we're going to get into the guts of how agents work, and start
looking at what the agent arms do. The first thing we'll look at is the agent's
state, and the three arms for managing it:
These arms handle what we call an agent's "lifecycle".
An agent's lifecycle starts when it's first installed. At this point, the
on-init arm is called. This is the only time
on-init is ever
called - its purpose is just to initialize the agent. The
on-init arm might be
very simple and just set an initial value for the state, or even do nothing at
all and return the agent core exactly as-is. It may also be more complicated,
and perform some scries to obtain extra data or
check that another agent is also installed. It might send off some
other agents or vanes to do things like load data in to the
agent, bind an Eyre endpoint, or anything else. It all depends on the needs of
your particular application. If
on-init fails for whatever reason, the agent
installation will fail and be aborted.
Once initialized, an agent will just go on doing its thing - processing events, updating its state, producing effects, etc. At some point, you'll likely want to push an update for your agent. Maybe it's a bug fix, maybe you want to add extra features. Whatever the reason, you need to change the source code of your agent, so you commit a modified version of the file to Clay. When the commit completes, Gall updates the app as follows:
- The agent's
on-savearm is called, which packs the agent's state in a
vaseand exports it.
- The new version of the agent is built and loaded into Gall.
- The previously exported
vaseis passed to the
on-loadarm of the newly built agent. The
on-loadarm will process it, convert it to the new version of the state if necessary, and load it back into the state of the agent.
vase is just a cell of
[type-of-the-noun the-noun]. Most data an agent
sends or receives will be encapsulated in a vase. A vase is made with the
!>) rune like
!>(some-data), and unpacked with the
!<) rune like
!<(type-to-extract vase). Have a read through the
vase section of the type
reference for details.
We'll look at the three arms described here in a little more detail, but first we need to touch on the state itself.
Versioned state type
In the previous lesson we introduced the idea of composing additional cores into the subject of the agent core. Here we'll look at using such a core to define the type of the agent's state. In principle, we could make it as simple as this:
|% +$ my-state-type @ud --
However, when you update your agent as described in the Lifecycle
section, you may want to change the type of the state itself. This means
on-load might find different versions of the state in the
vase it receives,
and it might not be able to distinguish between them.
For example, if you were creating an agent for a To-Do task management app, your
tasks might initially have a
?(%todo %done) union to specify whether they're
complete or not. Something like:
(map task=@t status=?(%todo %done))
At some point, you might want to add a third status to represent "in progress",
which might involve changing
(map title=@t status=?(%todo %done %work))
The conventional way to keep this managable and reliably differentiate possible
state types is to have versioned states. The first version of the state would
typically be called
state-0, and its head would be tagged with
when you change the state's type in an update, you'd add a new structure called
state-1 and tag its head with
%1. The next would then be
state-2, and so
In addition to each of those individual state versions, you'd also define a
versioned-state, which just contains a union of all the
possible states. This way, the vase
on-load receives can be unpacked to a
versioned-state type, and then a
?-) expression can switch on
the head (
%2, etc) and process each one appropriately.
For example, your state definition core might initially look like:
|% +$ versioned-state $% state-0 == +$ state-0 [%0 tasks=(map title=@t status=?(%todo %done))] --
When you later update your agent with a new state version, you'd change it to:
|% +$ versioned-state $% state-0 state-1 == +$ state-0 [%0 tasks=(map title=@t status=?(%todo %done))] +$ state-1 [%1 tasks=(map title=@t status=?(%todo %done %work))] --
Another reason for versioning the state type is that there may be cases where the state type doesn't change, but you still want to apply special transition logic for an old state during upgrade. For example, you may need to reprocess the data for a new feature or to fix a bug.
Adding the state
Along with a core defining the type of the state, we also need to actually add it to the subject of the core. The conventional way to do this is by adding the following immediately before the agent core itself:
=| state-0 =* state -
The first line bunts (produces the default value) of the state type we defined
in the previous core, and adds it to the head of the subject without a face.
The next line uses tistar to give it
the name of
state. You might wonder why we don't just give it a face when we
bunt it and skip the tistar part. If we did that, we'd have to refer to
tasks.state. With tistar, we can just reference
tasks while also being
able to reference the whole
state when necessary.
Note that adding the state like this only happens when the agent is built - from then on the arms of our agent will just modify it.
State management arms
We've described the basic lifecycle process and the purpose of each state management arm. Now let's look at each arm in detail:
This arm takes no argument, and produces a
(quip card _this). It's called
exactly once, when the agent is first installed. Its purpose is to initialize
(quip a b) is equivalent to
[(list a) b], see the types
reference for details.
card is a message to another agent or vane. We'll discuss
cards in detail
this is our agent core, which we give the
this alias in the virtual arm
described in the previous lesson. The underscore at the beginning is the
irregular syntax for the buccab (
rune. Buccab is like an inverted bunt - instead of producing the default value
of a type, instead it produces the type of some value. So
_this means "the
this" - the type of our agent core.
Recall that in the last lesson, we said that most arms return a cell of
[effects new-agent-core]. That's exactly what
(quip card _this) is.
This arm takes no argument, and produces a
vase. Its purpose is to export the
state of an agent - the state is packed into the vase it produces. The main time
it's called is when an agent is upgraded. When that happens, the agent's state
is exported with
on-save, the new version of the agent is compiled and loaded,
and then the state is imported back into the new version of the agent via the
As well as the agent upgrade process,
on-save is also used when an agent is
suspended or an app is uninstalled, so that the state can be restored when it's
resumed or reinstalled.
The state is packed in a vase with the
!>) rune, like
This arm takes a
vase and produces a
(quip card _this). Its purpose is to
import a state previously exported with
you'd have used a versioned state as described above,
so this arm would test which state version the imported data has, convert data
from an old version to the new version if necessary, and load it into the
state wing of the subject.
Here's a new agent to demonstrate the concepts we've discussed here:
/+ default-agent, dbug |% +$ versioned-state $% state-0 == +$ state-0 [%0 val=@ud] +$ card card:agent:gall -- %- agent:dbug =| state-0 =* state - ^- agent:gall |_ =bowl:gall +* this . def ~(. (default-agent this %.n) bowl) :: ++ on-init ^- (quip card _this) `this(val 42) :: ++ on-save ^- vase !>(state) :: ++ on-load |= old-state=vase ^- (quip card _this) =/ old !<(versioned-state old-state) ?- -.old %0 `this(state old) == :: ++ on-poke on-poke:def ++ on-watch on-watch:def ++ on-leave on-leave:def ++ on-peek on-peek:def ++ on-agent on-agent:def ++ on-arvo on-arvo:def ++ on-fail on-fail:def --
Let's break it down and have a look at the new parts we've added. First, the state core:
|% +$ versioned-state $% state-0 == +$ state-0 [%0 val=@ud] +$ card card:agent:gall --
state-0 we've defined the structure of our state, which is just a
We've tagged the head with a
%0 constant representing the version number, so
on-load can easily test the state version. In
versioned-state we've created
a union and just added our
state-0 type. We've added an extra
card arm as
well, just so we can use
card as a type, rather than the unweildy
After that core, we have the usual
agent:dbug call, and then we have this:
=| state-0 =* state -
We've just bunted the
state-0 type, which will produce
[%0 val=0], pinning
it to the head of the subject. Then, we've use
=*) to give it a name of
Inside our agent core, we have
++ on-init ^- (quip card _this) `this(val 42)
a(b c) syntax is the irregular form of the
%=) rune. You'll likely be
familiar with this from recursive functions, where you'll typically call the buc
arm of a trap like
$(a b, c d, ...). It's the same concept here - we're saying
this (our agent core) with
val replaced by
on-init is only
called when the agent is first installed, we're just initializing the state.
Next we have
++ on-save ^- vase !>(state)
This exports our agent's state, and is called during upgrades, suspensions, etc.
We're having it pack the
state value in a
Finally, we have
++ on-load |= old-state=vase ^- (quip card _this) =/ old !<(versioned-state old-state) ?- -.old %0 `this(state old) ==
It takes in the old state in a
vase, then unpacks it to the
type we defined earlier. We test its head for the version, and load it back into
the state of our agent if it matches. This test is a bit redundant at this stage
since we only have one state version, but you'll soon see the purpose of it.
You can save it as
/app/lifecycle.hoon in the
%base desk and
|commit %base. Then, run
|rein %base [& %lifecycle] to start it.
Let's try inspecting our state with
> [%0 val=42] > :lifecycle +dbug >=
dbug can also dig into the state with the
%state argument, printing the value of the specified face:
> 42 > :lifecycle +dbug [%state %val] >=
Next, we're going to modify our agent and change the structure of the state so
we can test out the upgrade process. Here's a modified version, which you can
again save in
/+ default-agent, dbug |% +$ versioned-state $% state-0 state-1 == +$ state-0 [%0 val=@ud] +$ state-1 [%1 val=[@ud @ud]] +$ card card:agent:gall -- %- agent:dbug =| state-1 =* state - ^- agent:gall |_ =bowl:gall +* this . def ~(. (default-agent this %.n) bowl) :: ++ on-init ^- (quip card _this) `this(val [27 32]) :: ++ on-save ^- vase !>(state) :: ++ on-load |= old-state=vase ^- (quip card _this) =/ old !<(versioned-state old-state) ?- -.old %1 `this(state old) %0 `this(state 1+[val.old val.old]) == :: ++ on-poke on-poke:def ++ on-watch on-watch:def ++ on-leave on-leave:def ++ on-peek on-peek:def ++ on-agent on-agent:def ++ on-arvo on-arvo:def ++ on-fail on-fail:def --
As soon as you
|commit it, Gall will immediately export the existing state
on-save, build the new version of the agent, then import the state back
In the state definition core, you'll see we've added a new state version with a different structure:
+$ versioned-state $% state-0 state-1 == +$ state-0 [%0 val=@ud] +$ state-1 [%1 val=[@ud @ud]] +$ card card:agent:gall --
We've also changed the part that adds the state, so it uses the new version instead:
=| state-1 =* state -
on-init, we've updated it to initialize the state with a value that fits the new type we've defined:
++ on-init ^- (quip card _this) `this(val [27 32])
on-init won't be called in this case, but if someone were to directly install
this new version of the agent, it would be, so we still need to update it.
on-save has been left unchanged, but
on-load has been updated like so:
++ on-load |= old-state=vase ^- (quip card _this) =/ old !<(versioned-state old-state) ?- -.old %1 `this(state old) %0 `this(state 1+[val.old val.old]) ==
We've updated the
?- expression with a new case that handles our new state
type, and for the old state type we've added a function that converts it to the
new type - in this case by duplicating
val and changing the head-tag from
%1. This is an extremely simple state type transition function - it would
likely be more complicated for an agent with real functionality.
a+b syntax (as in
1+[val.old val.old]) forms a cell of the
%a and the noun
b. The constant may either be an integer or a
> foo+'bar' [%foo 'bar'] > 42+'bar' [%42 'bar']
Let's now use
dbug to confirm our state has successfully been updated to the new
> [%1 val=[42 42]] > :lifecycle +dbug >=
- The app lifecycle rougly consists of initialization, state export, upgrade, state import and state version transition.
- This is managed by three arms:
on-initinitializes the agent and is called when it's first installed.
on-saveexports the agent's state and is called during upgrade or when an app is suspended.
on-loadimports an agent's state and is called during upgrade or when an app is unsuspended. It also handles converting data from old state versions to new state versions.
- The type of an agent's state is typically defined in a separate core.
- The state type is typically versioned, with a new type definition for each version of the state.
- The state is initially added by bunting the state type and then naming it
statewith the tistar (
=*) rune, so its contents can be referenced directly.
vaseis a cell of
(quip a b)is the same as
[(list a) b], and is the
[effects new-agent-core]pair returned by many arms of an agent core.
- Run through the example yourself on a fake ship if you've not done so already.
- Have a look at the
vaseentry in the type reference.
- Have a look at the
quipentry in the type reference.
- Try modifying the second version of the agent in the example
section, adding a third state version. Include functions in the wuthep
on-loadto convert old versions to your new state type.