mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-08-16 17:20:35 +03:00
Merge pull request #400 from urbit/update-gall-ref
bring gall documentation up-to-date
This commit is contained in:
tinnus-napbus
GitHub
commit
017d1ac435
@ -4,3 +4,20 @@ weight = 70
|
||||
sort_by = "weight"
|
||||
insert_anchor_links = "right"
|
||||
+++
|
||||
|
||||
## [Overview](/reference/arvo/gall/gall)
|
||||
|
||||
An overview of Eyre and its capabilities.
|
||||
|
||||
## [API Reference](/reference/arvo/gall/gall-api)
|
||||
|
||||
Reference documentation of both Gall's vane API and the API available to
|
||||
agents.
|
||||
|
||||
## [Scry Reference](/reference/arvo/gall/scry)
|
||||
|
||||
Reference documentation of Gall scry endpoints.
|
||||
|
||||
## [Data Types](/reference/arvo/gall/data-types)
|
||||
|
||||
Reference documentation of Gall's types as defined in `lull.hoon`.
|
||||
|
||||
@ -5,41 +5,60 @@ weight = 5
|
||||
|
||||
This document describes the data types for Gall defined in `lull.hoon`.
|
||||
|
||||
|
||||
## `bitt`
|
||||
|
||||
Incoming subscriptions.
|
||||
|
||||
```hoon
|
||||
+$ bitt (map duct (pair ship path))
|
||||
```
|
||||
|
||||
Incoming subscriptions.
|
||||
This is the structure Gall uses to keep track of incoming subscriptions
|
||||
for a Gall agent. The `sup` field of a [`bowl`](#bowl) contains the
|
||||
`bitt` for our agent.
|
||||
|
||||
This is the structure Gall uses to keep track of subscribers to our Gall agent.
|
||||
The `sup` field of a [`bowl`](#bowl) contains the `bitt` for our agent.
|
||||
---
|
||||
|
||||
## `boat`
|
||||
|
||||
```hoon
|
||||
+$ boat
|
||||
%+ map [=wire =ship =term]
|
||||
[acked=? =path]
|
||||
```
|
||||
|
||||
Outgoing subscriptions.
|
||||
|
||||
This is the structure Gall uses to keep track of subscriptions our agent has
|
||||
initiated. The `wex` field of a [`bowl`](#bowl) contails the `boat` for that
|
||||
agent.
|
||||
```hoon
|
||||
+$ boat (map [=wire =ship =term] [acked=? =path])
|
||||
```
|
||||
|
||||
The `wire` field is the `wire` which [`sign:agent`](#signagent)s will come in on.
|
||||
The `ship` and `term` fields are the ship and the name of the agent to which our
|
||||
agent has subscribed.
|
||||
This is the structure Gall uses to keep track of subscriptions our agent
|
||||
has initiated. The `wex` field of a [`bowl`](#bowl) contails the `boat`
|
||||
for that agent.
|
||||
|
||||
The `acked` field is `%.y` if they have acknowledged our subscription request,
|
||||
and `%.n` if they have not. The `path` field is the `path` on the other agent to
|
||||
which our agent has subscribed.
|
||||
The `wire` field is the `wire` which [`sign:agent`](#signagent)s will
|
||||
come in on. The `ship` and `term` fields are the ship and the name of
|
||||
the agent to which our agent has subscribed.
|
||||
|
||||
The `acked` field is `%.y` if they have acknowledged our subscription
|
||||
request with a `%watch-ack`, and `%.n` if they have not. The `path`
|
||||
field is the `path` on the other agent to which our agent has
|
||||
subscribed.
|
||||
|
||||
---
|
||||
|
||||
## `boar`
|
||||
|
||||
Subscription nonces.
|
||||
|
||||
```hoon
|
||||
+$ boar (map [=wire =ship =term] nonce=@)
|
||||
```
|
||||
|
||||
Gall uses this to keep track of nonces for subscriptions.
|
||||
|
||||
---
|
||||
|
||||
## `bowl`
|
||||
|
||||
Additional agent state.
|
||||
|
||||
```hoon
|
||||
+$ bowl :: standard app state
|
||||
$: $: our=ship :: host
|
||||
@ -56,11 +75,9 @@ which our agent has subscribed.
|
||||
eny=@uvJ :: entropy
|
||||
now=@da :: current time
|
||||
byk=beak :: load source
|
||||
== == :: ::
|
||||
== == ::
|
||||
```
|
||||
|
||||
Additional agent state.
|
||||
|
||||
A `bowl` is given to the agent core each time an event comes in. The fields are
|
||||
as follows:
|
||||
|
||||
@ -82,24 +99,49 @@ as follows:
|
||||
`case` will be `[%da @da]` where the `@da` is the when the agent was loaded. A
|
||||
`beak` is a triple of `[ship desk case]`.
|
||||
|
||||
---
|
||||
|
||||
## `dude`
|
||||
|
||||
Agent name.
|
||||
|
||||
```hoon
|
||||
+$ dude term
|
||||
```
|
||||
|
||||
Agent name.
|
||||
---
|
||||
|
||||
## `gill`
|
||||
|
||||
A general contact.
|
||||
|
||||
```hoon
|
||||
+$ gill (pair ship term)
|
||||
```
|
||||
|
||||
A general contact: A pair of the ship and agent name.
|
||||
A pair of the ship and agent name.
|
||||
|
||||
---
|
||||
|
||||
## `load`
|
||||
|
||||
Loadout.
|
||||
|
||||
```hoon
|
||||
+$ load (list [=dude =beak =agent])
|
||||
```
|
||||
|
||||
The [`dude`](#dude) is the agent name, the `beak` is the ship/desk/case
|
||||
in which it resides, and the [`agent`](#agent) is the built agent
|
||||
itself. Clay passes this to Gall when it builds or modifies the state of
|
||||
running agents.
|
||||
|
||||
---
|
||||
|
||||
## `scar`
|
||||
|
||||
Opaque duct - used internally.
|
||||
|
||||
```hoon
|
||||
+$ scar
|
||||
$: p=@ud
|
||||
@ -108,40 +150,30 @@ A general contact: A pair of the ship and agent name.
|
||||
==
|
||||
```
|
||||
|
||||
Opaque duct - used internally.
|
||||
---
|
||||
|
||||
## `suss`
|
||||
|
||||
Configuration report.
|
||||
|
||||
```hoon
|
||||
+$ suss (trel dude @tas @da)
|
||||
```
|
||||
|
||||
Configuration report.
|
||||
---
|
||||
|
||||
## `well`
|
||||
|
||||
Desk and agent.
|
||||
|
||||
```hoon
|
||||
+$ well (pair desk term)
|
||||
```
|
||||
|
||||
Desk and agent.
|
||||
|
||||
## `neat`
|
||||
|
||||
```hoon
|
||||
+$ neat
|
||||
$% [%arvo =note-arvo]
|
||||
[%agent [=ship name=term] =deal]
|
||||
[%pyre =tang]
|
||||
==
|
||||
```
|
||||
|
||||
Like a [`note:agent`](#noteagent), except the `%agent` case has a [`deal`](#deal) instead
|
||||
of just a [`task:agent`](#taskagent). This is used for messages that come in over the
|
||||
network and would not be used manually.
|
||||
|
||||
## `deal`
|
||||
|
||||
An agent task or raw poke.
|
||||
|
||||
```hoon
|
||||
+$ deal
|
||||
$% [%raw-poke =mark =noun]
|
||||
@ -149,12 +181,17 @@ network and would not be used manually.
|
||||
==
|
||||
```
|
||||
|
||||
Like a [`task:agent`](#taskagent) but with the additional case of a raw poke.
|
||||
This is used for messages that come in over the network and would not be used
|
||||
manually.
|
||||
The additional `%raw-poke` is for pokes which haven't yet been converted
|
||||
to an ordinary `%poke` by molding the `noun` with the specified `mark`
|
||||
core. This structure is passed around on the kernel level, it would not
|
||||
be used in userspace.
|
||||
|
||||
---
|
||||
|
||||
## `unto`
|
||||
|
||||
An agent gift or a raw fact.
|
||||
|
||||
```hoon
|
||||
+$ unto
|
||||
$% [%raw-fact =mark =noun]
|
||||
@ -162,9 +199,24 @@ manually.
|
||||
==
|
||||
```
|
||||
|
||||
Like a [`sign:agent`](#signagent) but with the additional case of a raw fact.
|
||||
This is used for messages that come in over the network and would not be used
|
||||
manually.
|
||||
The additional `%raw-fact` is for facts which haven't yet been converted
|
||||
to an ordinary `%fact` by molding the `noun` it with the specified
|
||||
`mark` core. This structure is passed around on the kernel level, it
|
||||
would not be used in userspace.
|
||||
|
||||
---
|
||||
|
||||
## `verb`
|
||||
|
||||
Verbosity flags.
|
||||
|
||||
```hoon
|
||||
+$ verb ?(%odd)
|
||||
```
|
||||
|
||||
Flags to set Gall verbosity. Currently only `%odd` for unusual errors.
|
||||
|
||||
---
|
||||
|
||||
## `agent`
|
||||
|
||||
@ -175,10 +227,10 @@ manually.
|
||||
```
|
||||
|
||||
Container for Gall agent types. The most significant arm is
|
||||
[`form:agent`](#formagent), which specifies the structure of the agent itself.
|
||||
There are also some additional structures defined here, mostly defining the
|
||||
kinds of messages agents can send. The different arms of the core in `agent`
|
||||
are considered separately below.
|
||||
[`form:agent`](#formagent), which specifies the structure of the agent
|
||||
itself. There are also some additional structures defined here, mostly
|
||||
defining the kinds of messages agents can send. The different arms of
|
||||
the core in `agent` are considered separately below.
|
||||
|
||||
### `step:agent`
|
||||
|
||||
@ -186,8 +238,12 @@ are considered separately below.
|
||||
+$ step (quip card form)
|
||||
```
|
||||
|
||||
A cell of [`card:agent`](#cardagent)s to be sent and a new agent state. This is the
|
||||
type returned by most arms of an agent. A `(quip a b)` is the same as `[(list a) b]`, it's just a more convenient way to specify it.
|
||||
A cell of [`card:agent`](#cardagent)s to be sent and a new agent state.
|
||||
This is the type returned by most arms of an agent. A `(quip a b)` is
|
||||
the same as `[(list a) b]`, it's just a more convenient way to specify
|
||||
it.
|
||||
|
||||
---
|
||||
|
||||
### `card:agent`
|
||||
|
||||
@ -195,9 +251,9 @@ type returned by most arms of an agent. A `(quip a b)` is the same as `[(list a)
|
||||
+$ card (wind note gift)
|
||||
```
|
||||
|
||||
An effect - typically a message to be sent to another agent or vane. A list of
|
||||
these are returned by most agent arms along with a new state in a
|
||||
[`step:agent`](#stepagent). A `wind` is the following:
|
||||
An effect - typically a message to be sent to another agent or vane. A
|
||||
list of these are returned by most agent arms along with a new state in
|
||||
a [`step:agent`](#stepagent). A `wind` is the following:
|
||||
|
||||
```hoon
|
||||
++ wind
|
||||
@ -213,9 +269,11 @@ Gall will not allow a `%slip`, so in practice a `card` will be one of:
|
||||
- `[%pass path note]`
|
||||
- `[%give gift]`
|
||||
|
||||
For `%pass`, `p` specifies the `wire` on which a response should be returned.
|
||||
See [`note:agent`](#noteagent) and [`gift:agent`](#giftagent) below for details of their
|
||||
types.
|
||||
For `%pass`, `p` specifies the `wire` on which a response should be
|
||||
returned. See [`note:agent`](#noteagent) and [`gift:agent`](#giftagent)
|
||||
below for details of their types.
|
||||
|
||||
---
|
||||
|
||||
### `note:agent`
|
||||
|
||||
@ -232,13 +290,15 @@ types.
|
||||
```
|
||||
|
||||
The type for messages initiated by our agent. This is opposed to
|
||||
[`gift:agent`](#giftagent), which is the type for responding to other agents or
|
||||
vanes, or for sending out updates to subscribers. The three cases are:
|
||||
[`gift:agent`](#giftagent), which is the type for responding to other
|
||||
agents or vanes, or for sending out updates to subscribers. The three
|
||||
cases are:
|
||||
|
||||
- `%agent`: Poke another agent, subscribe to another agent, or cancel a
|
||||
subscription to another agent. The `ship` and `name` fields are the ship and
|
||||
agent to which the `task` should be sent. The `task` is the request itself,
|
||||
see [`task:agent`](#taskagent) below for its possible types.
|
||||
subscription to another agent. The `ship` and `name` fields are the
|
||||
ship and agent to which the `task` should be sent. The `task` is the
|
||||
request itself, see [`task:agent`](#taskagent) below for its possible
|
||||
types.
|
||||
- `%arvo`: Pass a `task` to a vane. The type of a `note-arvo` is:
|
||||
```hoon
|
||||
+$ note-arvo
|
||||
@ -256,19 +316,23 @@ vanes, or for sending out updates to subscribers. The three cases are:
|
||||
[@tas %meta vase]
|
||||
==
|
||||
```
|
||||
You can refer to the `/sys/lull.hoon` source code for all the possible vane
|
||||
tasks, or see each vane's API Reference section in the [Arvo
|
||||
You can refer to the `/sys/lull.hoon` source code for all the possible
|
||||
vane tasks, or see each vane's API Reference section in the [Arvo
|
||||
documentation](/reference/arvo/overview)
|
||||
- `%pyre`: This is for aborting side-effects initiated during agent
|
||||
installation. The `tang` is an error message.
|
||||
- `%grow`/`%tomb`/`%cull`: These are used for publishing and managing data
|
||||
available for remote scries. For more information, see the [remote scries
|
||||
guide](/guides/additional/remote-scry).
|
||||
- `%grow`/`%tomb`/`%cull`: These are used for publishing and managing
|
||||
data available for remote scries. For more information, see the
|
||||
[remote scries guide](/guides/additional/remote-scry).
|
||||
|
||||
A `note:agent` is always wrapped in a `%pass` [`card:agent`](#cardagent).
|
||||
|
||||
---
|
||||
|
||||
### `task:agent`
|
||||
|
||||
The types of messages initiated by our agent and sent to another agent.
|
||||
|
||||
```hoon
|
||||
+$ task
|
||||
$% [%watch =path]
|
||||
@ -279,10 +343,9 @@ A `note:agent` is always wrapped in a `%pass` [`card:agent`](#cardagent).
|
||||
==
|
||||
```
|
||||
|
||||
The types of messages initiated by our agent and sent to another agent. This is
|
||||
in contrast to [`gift:agent`](#giftagent)s, which are responses to incoming
|
||||
messages from agents or updates to agents already subscribed. The five kinds
|
||||
are:
|
||||
This is in contrast to [`gift:agent`](#giftagent)s, which are responses
|
||||
to incoming messages from agents or updates to agents already
|
||||
subscribed. The five kinds of `task:agent` are:
|
||||
|
||||
- `%watch`: Subscribe to `path` on the target ship and agent.
|
||||
- `%watch-as`: Same as `%watch`, except you ask the target's Gall to convert
|
||||
@ -298,8 +361,13 @@ are:
|
||||
|
||||
A `task:agent` is always wrapped in a `%pass` [`card:agent`](#cardagent).
|
||||
|
||||
---
|
||||
|
||||
### `gift:agent`
|
||||
|
||||
The types of messages our agent can either send in response to messages
|
||||
from other agents, or send to subscribed agents.
|
||||
|
||||
```hoon
|
||||
+$ gift
|
||||
$% [%fact paths=(list path) =cage]
|
||||
@ -309,37 +377,46 @@ A `task:agent` is always wrapped in a `%pass` [`card:agent`](#cardagent).
|
||||
==
|
||||
```
|
||||
|
||||
The types of messages our agent can either send in response to messages from
|
||||
other agents, or send to subscribed agents. This is in contrast to
|
||||
[`task:agent`](#taskagent)s, which are messages to other agents our agent
|
||||
initiates rather than sends in response. The four kinds are:
|
||||
This is in contrast to [`task:agent`](#taskagent)s, which are messages
|
||||
to other agents our agent initiates rather than sends in response. The
|
||||
four kinds of `gift:agent` are:
|
||||
|
||||
- `%fact`: An update to existing subscribers. The `paths` field specifies which
|
||||
subscription paths the update should go out to. The `cage` is the data, and is
|
||||
a `[mark vase]`.
|
||||
- `%fact`: An update to existing subscribers. The `paths` field
|
||||
specifies which subscription paths the update should go out to. The
|
||||
`cage` is the data, and is a `[mark vase]`.
|
||||
- `%kick`: Kick subscriber, ending their subscription. The `paths` field
|
||||
specifies which paths the subscriber should be kicked from, and the `ship`
|
||||
field specifies the ship to kick. If the `ship` field is null, all subscribers
|
||||
on the specified paths are kicked. Gall will automatically remove the
|
||||
subscription from our agent's [`bitt`](#bitt) (inbound subscription `map`),
|
||||
and subscriber will no longer receive updates on the `path`s in question.
|
||||
- `%watch-ack`: Acknowledge a subscription request. If `p` is null, it's an ack
|
||||
(positive acknowledgement), and if `p` is non-null, it's a nack (negative
|
||||
acknowledgement). Simply crashing will caused Gall to nack a subscription
|
||||
request, and not crashing but not explicitly producing a `%watch-ack` `gift`
|
||||
will cause Gall to ack a subscription request. Therefore, you'd typically only
|
||||
explicitly produce a `%watch-ack` `gift` if you wanted to nack a subscription
|
||||
request with a custom error in the `tang`.
|
||||
- `%poke-ack`: Acknowledge a poke. If `p` is null, it's an ack, and if `p` is
|
||||
non-null, it's a nack. Simply crashing will cause Gall to nack a poke, and not
|
||||
crashing but not explicitly producing a `%poke-ack` `gift` will cause Gall to
|
||||
ack a poke. Therefore, you'd typically only explicitly produce a `%poke-ack`
|
||||
`gift` if you wanted to nack a poke with a custom error in the `tang`.
|
||||
specifies which paths the subscriber should be kicked from, and the
|
||||
`ship` field specifies the ship to kick. If the `ship` field is null,
|
||||
all subscribers on the specified paths are kicked. Gall will
|
||||
automatically remove the subscription from our agent's [`bitt`](#bitt)
|
||||
(inbound subscription `map`), and subscriber will no longer receive
|
||||
updates on the `path`s in question.
|
||||
- `%watch-ack`: Acknowledge a subscription request. If `p` is null, it's
|
||||
an ack (positive acknowledgement), and if `p` is non-null, it's a nack
|
||||
(negative acknowledgement). Simply crashing will caused Gall to nack a
|
||||
subscription request, and not crashing but not explicitly producing a
|
||||
`%watch-ack` `gift` will cause Gall to ack a subscription request.
|
||||
Therefore, you'd typically only explicitly produce a `%watch-ack`
|
||||
`gift` if you wanted to nack a subscription request with a custom
|
||||
error in the `tang`.
|
||||
- `%poke-ack`: Acknowledge a poke. If `p` is null, it's an ack, and if
|
||||
`p` is non-null, it's a nack. Simply crashing will cause Gall to nack
|
||||
a poke, and not crashing but not explicitly producing a `%poke-ack`
|
||||
`gift` will cause Gall to ack a poke. Therefore, you'd typically only
|
||||
explicitly produce a `%poke-ack` `gift` if you wanted to nack a poke
|
||||
with a custom error in the `tang`.
|
||||
|
||||
A `gift:agent` is always wrapped in a `%give` [`card:agent`](#cardagent).
|
||||
A `gift:agent` is always wrapped in a `%give`
|
||||
[`card:agent`](#cardagent).
|
||||
|
||||
---
|
||||
|
||||
### `sign:agent`
|
||||
|
||||
A `sign` is like a [`gift:agent`](#giftagent) but it's something that
|
||||
comes _in_ to our agent from another agent rather than something we send
|
||||
out.
|
||||
|
||||
```hoon
|
||||
+$ sign
|
||||
$% [%poke-ack p=(unit tang)]
|
||||
@ -349,31 +426,34 @@ A `gift:agent` is always wrapped in a `%give` [`card:agent`](#cardagent).
|
||||
==
|
||||
```
|
||||
|
||||
A `sign` is like a [`gift:agent`](#giftagent) but it's something that comes
|
||||
_in_ to our agent from another agent rather than something we send out. The
|
||||
possible types are:
|
||||
The possible types are:
|
||||
|
||||
- `%poke-ack`: Another agent has acked (positively acknowledged) or nacked
|
||||
(negatively acknowledged) a `%poke` [`task:agent`](#taskagent) we previously
|
||||
sent. It's an ack if `p` is null and a nack if `p` is non-null. The `tang`
|
||||
contains an error or traceback if it's a nack.
|
||||
- `%poke-ack`: Another agent has acked (positively acknowledged) or
|
||||
nacked (negatively acknowledged) a `%poke` [`task:agent`](#taskagent)
|
||||
we previously sent. It's an ack if `p` is null and a nack if `p` is
|
||||
non-null. The `tang` contains an error or traceback if it's a nack.
|
||||
- `%watch-ack`: Another agent has acked or nacked a `%watch`
|
||||
[`task:agent`](#taskagent) (subscription request) we previously sent. It's an
|
||||
ack if `p` is null and a nack if `p` is non-null. The `tang` contains an error
|
||||
or traceback if it's a nack. If it's a nack, Gall will automatically remove
|
||||
the subscription from our agent's [`boat`](#boat) (outbound subscription
|
||||
map).
|
||||
- `%fact`: An update from another agent to which we've previously subscribed
|
||||
with a `%watch` [`task:agent`](#taskagent) (subscription request). The `cage`
|
||||
contains the data, and is a `[mark vase]`.
|
||||
- `%kick`: Our subscription to another agent has been ended, and we'll no longer
|
||||
receive updates. A `%kick` may be intentional, but it may also happen due to
|
||||
certain network conditions or other factors. As a result, it's best to try and
|
||||
resubscribe with another `%watch` [`task:agent`](#taskagent), and if they
|
||||
nack the `%watch`, we can conclude it was intentional and give up.
|
||||
[`task:agent`](#taskagent) (subscription request) we previously sent.
|
||||
It's an ack if `p` is null and a nack if `p` is non-null. The `tang`
|
||||
contains an error or traceback if it's a nack. If it's a nack, Gall
|
||||
will automatically remove the subscription from our agent's
|
||||
[`boat`](#boat) (outbound subscription map).
|
||||
- `%fact`: An update from another agent to which we've previously
|
||||
subscribed with a `%watch` [`task:agent`](#taskagent) (subscription
|
||||
request). The `cage` contains the data, and is a `[mark vase]`.
|
||||
- `%kick`: Our subscription to another agent has been ended, and we'll
|
||||
no longer receive updates. A `%kick` may be intentional, but it may
|
||||
also happen due to certain network conditions or other factors. As a
|
||||
result, it's best to try and resubscribe with another `%watch`
|
||||
[`task:agent`](#taskagent), and if they nack the `%watch`, we can
|
||||
conclude it was intentional and give up.
|
||||
|
||||
---
|
||||
|
||||
### `form:agent`
|
||||
|
||||
This defines the structure of the agent itself.
|
||||
|
||||
```hoon
|
||||
++ form
|
||||
$_ ^|
|
||||
@ -419,7 +499,8 @@ possible types are:
|
||||
--
|
||||
```
|
||||
|
||||
This defines the structure of the agent itself. The agent is a door with a [`bowl`](#bowl) as its sample and exactly ten arms. Below we'll describe each arm briefly.
|
||||
The agent is a door with a [`bowl`](#bowl) as its sample and exactly ten
|
||||
arms. Below we'll describe each arm briefly.
|
||||
|
||||
#### `on-init`
|
||||
|
||||
@ -447,16 +528,16 @@ This arm is called when another agent subscribes to our agent.
|
||||
- Accepts: `path`
|
||||
- Produces: [`step:agent`](#stepagent)
|
||||
|
||||
This arm is called when another agent unsubscribes from a subscription path on
|
||||
our agent.
|
||||
This arm is called when another agent unsubscribes from a
|
||||
subscription path on our agent.
|
||||
|
||||
#### `on-peek`
|
||||
|
||||
- Accepts: `path`
|
||||
- Produces: `(unit (unit cage))`
|
||||
|
||||
This arm is called when a [scry](/reference/arvo/concepts/scry) is performed on our
|
||||
agent.
|
||||
This arm is called when a [scry](/reference/arvo/concepts/scry) is
|
||||
performed on our agent.
|
||||
|
||||
#### `on-agent`
|
||||
|
||||
@ -471,7 +552,8 @@ This arm is called when another agent give our agent a
|
||||
- Accepts: `[wire sign-arvo]`
|
||||
- Produces: [`step:agent`](#stepagent)
|
||||
|
||||
This arm is called when a vane gives our agent a `gift`. A `sign-arvo` is:
|
||||
This arm is called when a vane gives our agent a `gift`. A `sign-arvo`
|
||||
is:
|
||||
|
||||
```hoon
|
||||
+$ sign-arvo
|
||||
@ -494,13 +576,15 @@ This arm is called when a vane gives our agent a `gift`. A `sign-arvo` is:
|
||||
==
|
||||
```
|
||||
|
||||
You can refer to the `/sys/lull.hoon` source code, or the API Reference of each
|
||||
vane in the [Arvo documentation](/reference/arvo/overview).
|
||||
You can refer to the `/sys/lull.hoon` source code, or the API Reference
|
||||
of each vane in the [Arvo documentation](/reference/arvo/overview).
|
||||
|
||||
#### `on-fail`
|
||||
|
||||
- Accepts: `[term tang]`
|
||||
- Produces: [`step:agent`](#stepagent)
|
||||
|
||||
This arm is called if certain errors occur in Gall, such as if our agent tries
|
||||
to create a duplicate subscription.
|
||||
This arm is called if certain errors occur in Gall, such as if our agent
|
||||
tries to create a duplicate subscription.
|
||||
|
||||
---
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -59,10 +59,11 @@ definable in a regular recursive data type).
|
||||
|
||||
## Specification
|
||||
|
||||
An agent is defined as a [core](/reference/glossary/core/) with a set of [arms](/reference/glossary/arm/) to handle various
|
||||
events. These handlers usually produce a list of effects and the next
|
||||
state of the agent. The interface definition can be found in
|
||||
`sys/lull.hoon`, which at the time of writing is:
|
||||
An agent is defined as a [core](/reference/glossary/core/) with a set of
|
||||
[arms](/reference/glossary/arm/) to handle various events. These
|
||||
handlers usually produce a list of effects and the next state of the
|
||||
agent. The interface definition can be found in `sys/lull.hoon`, which
|
||||
at the time of writing is:
|
||||
|
||||
```hoon
|
||||
++ agent
|
||||
@ -71,8 +72,13 @@ state of the agent. The interface definition can be found in
|
||||
+$ step (quip card form)
|
||||
+$ card (wind note gift)
|
||||
+$ note
|
||||
$% [%arvo =note-arvo]
|
||||
[%agent [=ship name=term] =task]
|
||||
$% [%agent [=ship name=term] =task]
|
||||
[%arvo note-arvo]
|
||||
[%pyre =tang]
|
||||
::
|
||||
[%grow =spur =page]
|
||||
[%tomb =case =spur]
|
||||
[%cull =case =spur]
|
||||
==
|
||||
+$ task
|
||||
$% [%watch =path]
|
||||
@ -82,8 +88,8 @@ state of the agent. The interface definition can be found in
|
||||
[%poke-as =mark =cage]
|
||||
==
|
||||
+$ gift
|
||||
$% [%fact path=(unit path) =cage]
|
||||
[%kick path=(unit path) ship=(unit ship)]
|
||||
$% [%fact paths=(list path) =cage]
|
||||
[%kick paths=(list path) ship=(unit ship)]
|
||||
[%watch-ack p=(unit tang)]
|
||||
[%poke-ack p=(unit tang)]
|
||||
==
|
||||
@ -134,6 +140,7 @@ state of the agent. The interface definition can be found in
|
||||
|~ [term tang]
|
||||
*(quip card _^|(..on-init))
|
||||
--
|
||||
--
|
||||
```
|
||||
|
||||
Here's a skeleton example of an implementation:
|
||||
|
||||
@ -215,6 +215,28 @@ A `cass:clay`, specifically the `%ud` kind.
|
||||
|
||||
---
|
||||
|
||||
### `%x`: remote scry file
|
||||
|
||||
A scry with a `%x` care and an agent in `q.beak` will get the value
|
||||
bound at the remote scry path given in the `spur`. The revision of the
|
||||
file must be given in the `beak` portion of the scry path. The general
|
||||
format is therefore:
|
||||
|
||||
```hoon
|
||||
[%gx /[ship]/[agent]/[file revision]//[file path]
|
||||
```
|
||||
|
||||
See the [remote scry guide](/guides/additional/remote-scry) for more
|
||||
details.
|
||||
|
||||
#### Produces
|
||||
|
||||
The type returned is an `(each page @uvI)`. If the file has been
|
||||
tombstoned, it'll be the `@uvI` hash of the file. Otherwise, it will be
|
||||
the data as a `page` (a pair of `mark` and `noun`).
|
||||
|
||||
---
|
||||
|
||||
### `%z`: hash of value at path
|
||||
|
||||
A scry with a `%z` care and an agent in `q.beak` will get the hash identifier
|
||||
|
||||
@ -1,86 +0,0 @@
|
||||
+++
|
||||
title = "Threads Reference"
|
||||
weight = 50
|
||||
+++
|
||||
|
||||
## Start thread
|
||||
|
||||
Poke `spider` with mark `%spider-start` and a vase containing `start-args`:
|
||||
|
||||
```hoon
|
||||
+$ start-args
|
||||
[parent=(unit tid) use=(unit tid) =beak file=term =vase]
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `parent` - optional `tid` of parent thread if the thread is a child. If specified, the child thread will be killed with the parent thread ends.
|
||||
- `use` - `tid` (thread ID) to give the new thread. Can be generated with something like `(scot %ta (cat 3 'my-agent_' (scot %uv (sham eny))))`. However you do it, make sure it's unique.
|
||||
- `beak` - A `$beak` is a triple of `[p=ship q=desk r=case]`. `p` is always our ship, `q` is the desk which contains the thread we want to run. `r` is a `case`, which specifies a desk revision and is a tagged union of:
|
||||
```hoon
|
||||
+$ case
|
||||
$% [%da p=@da] :: date
|
||||
[%tas p=@tas] :: label
|
||||
[%ud p=@ud] :: number
|
||||
==
|
||||
```
|
||||
You'll almost always just want the current revision, so you can specify the `case` as `da+now.bowl`. If the thread is on the same desk as the agent you can also just use `byk.bowl(r da+now)` for the `beak`.
|
||||
- `file` - name of the thread file in `/ted`. For example, if the thread you want to start is `/ted/foo/hoon` you'd specify `%foo`.
|
||||
- `vase` - `vase` to be given to the thread when it's started. Can be whatever or just `!>(~)` if it doesn't need any args.
|
||||
|
||||
#### Example
|
||||
|
||||
```hoon
|
||||
[%pass /some-path %agent [our.bowl %spider] %poke %spider-start !>([~ `tid byk.bowl %foo !>(~)])]
|
||||
```
|
||||
|
||||
## Stop thread
|
||||
|
||||
Poke `spider` with mark `%spider-stop` and a vase containing `[tid ?]`, where:
|
||||
|
||||
- `tid` - the `tid` of the thread you want to stop
|
||||
- `?` - whether thread should end nicely. If `%.y` it'll end with mark `%thread-done` and the bunt value of a vase. If `%.n` it'll end with mark `%thread-fail` and a `[term tang]` where `term` is `%cancelled` and `tang` is `~`.
|
||||
|
||||
#### Example
|
||||
|
||||
```hoon
|
||||
[%pass /some-path %agent [our.bowl %spider] %poke %spider-stop !>([tid %.y)]
|
||||
```
|
||||
|
||||
## Subscribe for result
|
||||
|
||||
Spider will send the result on `/thread-result/[tid]` so you can subscribe there for the result. You should subscribe before starting the thread.
|
||||
|
||||
The result will have a mark of either `%thread-fail` or `%thread-done`.
|
||||
|
||||
- `%thread-fail` - has a vase containing a `[term tang]` where `term` is an error message and `tang` is a traceback.
|
||||
- `%thread-done` - has a vase of the result of the thread.
|
||||
|
||||
#### Example
|
||||
|
||||
```hoon
|
||||
[%pass /some-path %agent [our.bowl %spider] %watch /thread-result/[tid]]
|
||||
```
|
||||
|
||||
## Subscribe to thread
|
||||
|
||||
You can subscribe to a thread on `/thread/[tid]/path`. Note this is for facts sent off by the thread while it's running, not the final result. The path depends on the particular thread.
|
||||
|
||||
#### Example
|
||||
|
||||
```hoon
|
||||
[%pass /some-path %agent [our.bowl %spider] %watch /thread/[tid]/thread-path]
|
||||
```
|
||||
|
||||
## Poke thread
|
||||
|
||||
To poke a thread you poke spider with a mark of `%spider-input` and a vase of `[tid cage]`.
|
||||
|
||||
- `tid` is the tid of the thread you want to poke
|
||||
- `cage` is whatever mark and vase you want to poke it with
|
||||
|
||||
#### Example
|
||||
|
||||
```hoon
|
||||
[%pass /some-path %agent [our.bowl %spider] %poke %spider-input !>([tid %foo !>('foooo')])]
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user