diff --git a/content/urbit-os/kernel/ames/README.md b/content/urbit-os/kernel/ames/README.md index 898fe039..ef598c3d 100644 --- a/content/urbit-os/kernel/ames/README.md +++ b/content/urbit-os/kernel/ames/README.md @@ -55,7 +55,11 @@ Ames encrypts every message using symmetric-key encryption by performing an elli When a peer suffers a continuity breach, Ames removes all messaging state related to it. Ames does not guarantee that all messages will be fully delivered to the now-stale peer. From Ames's perspective, the newly restarted peer is a new ship. Ames's guarantees are not maintained across a breach. -A vane can pass Ames a `%heed` task to request Ames track a peer's responsiveness. If our `%boon`'s to it start backing up locally, Ames will give a `%clog` back to the requesting vane containing the unresponsive peer's urbit address. This interaction does not use ducts as unique keys. Stop tracking a peer by sending Ames a `%jilt` task. +Ames and Gall apply backpressure to each other so that a peer whose agent cannot currently accept a message does not cause unbounded retries. + +When an agent will not take a `$plea`, Gall gives Ames a `%flub` gift; when it is ready again it gives a `%spur`. On the sending side, Ames halts the flow with a [`%halt`](tasks.md#halt) task, and restarts it with a [`%goad`](tasks.md#goad) once the remote agent is live. A halted flow stops re-sending and starts no new timers. + +Ames may also pass Gall a `%clog` task to signal that `%boon`s to a peer are backing up locally. Note that `%clog` is a `$task:gall` — it is no longer an Ames gift, and the older `%heed`/`%jilt` tasks that drove it have been removed. Debug output can be adjusted using `%sift` and `%spew` task's. diff --git a/content/urbit-os/kernel/ames/data-types.md b/content/urbit-os/kernel/ames/data-types.md index 2e7fc488..97a3b96a 100644 --- a/content/urbit-os/kernel/ames/data-types.md +++ b/content/urbit-os/kernel/ames/data-types.md @@ -77,6 +77,27 @@ Application-level message, as a `%pass`. - `.path` - Internal route on the receiving ship. - `.payload` - Semantic message contents. +## `$deep` {#deep} + +```hoon ++$ deep + $% [%nack =ship =nack=bone =message] + [%sink =ship =target=bone naxplanation=[=message-num =error]] + [%drop =ship =nack=bone =message-num] + [%cork =ship =bone] + [%kill =ship =bone] + [%ahoy =ship =bone] + [%prun =ship =user=path =duct =ames=path] + [%halt =ship agent=term =bone] + == +``` + +Deferred internal operations. Ames passes these to itself so that the work +happens in a later event rather than inside the current one. + +The `%deep` task carries a `$deep`, and the [`%halt`](tasks.md#halt) task is the +`%halt` case of it, written `$>(%halt deep)`. + ## `$spar` {#spar} ```hoon @@ -186,8 +207,8 @@ All Ames knows about a peer. +$ alien-agenda $: messages=(list [=duct =plea]) packets=(set =blob) - heeds=(set duct) - keens=(jug path duct) + keens=(jug [path ints] duct) + chums=(jug [path ints] duct) == ``` @@ -195,8 +216,8 @@ What to do when Ames learns a peer's life and keys. - `messages` - [$plea](#plea)s local vanes have asked Ames to send. - `packets` - Packets we've tried to send. -- `heeds` - Local tracking requests; passed through into [$peer-state](#peer-state). - `keens` - Subscribers to remote scry paths. +- `chums` - Subscribers to remote scry paths via `%chum`. ## `$peer-state` {#peer-state} @@ -214,10 +235,12 @@ What to do when Ames learns a peer's life and keys. snd=(map bone message-pump-state) rcv=(map bone message-sink-state) nax=(set [=bone =message-num]) - heeds=(set duct) closing=(set bone) corked=(set bone) keens=(map path keen-state) + =chain + tip=(jug =user=path [duct =ames=path]) + halt=(set bone) == ``` @@ -229,10 +252,12 @@ State for a peer with known life and keys. - `.snd` - Per-`$bone` message pumps to send messages as fragments. - `.rcv` - Per-`$bone` message sinks to assemble messages from fragments. - `.nax` - Unprocessed nacks (negative acknowledgments). -- `.heeds` - Listeners for `%clog` notifications. - `.closing`: Bones closed on the sender side. - `.corked`: Bones closed on both sender and receiver. - `.keens`: Remote scry state. +- `.chain`: Remote scry key chain. +- `.tip`: Outstanding subscription paths. +- `.halt`: Bones whose flows are halted by backpressure. See [`%halt`](tasks.md#halt). ## `$keen-state` {#keen-state} diff --git a/content/urbit-os/kernel/ames/scry.md b/content/urbit-os/kernel/ames/scry.md index 0349da87..7dd5d1c8 100644 --- a/content/urbit-os/kernel/ames/scry.md +++ b/content/urbit-os/kernel/ames/scry.md @@ -78,7 +78,12 @@ A scry with a `%x` `$care` and a `$path` of `/peers/[ship]` where `[ship]` is a } rcv={} nax={} - heeds={~[/gall/sys/lag /dill //term/1]} + closing={} + corked={} + keens={} + chain={} + tip={} + halt={} ] ``` diff --git a/content/urbit-os/kernel/ames/tasks.md b/content/urbit-os/kernel/ames/tasks.md index e8cf1e30..cacc8eb3 100644 --- a/content/urbit-os/kernel/ames/tasks.md +++ b/content/urbit-os/kernel/ames/tasks.md @@ -43,35 +43,48 @@ There are multiple `+on-hear` arms in `ames.hoon`. Here we refer to `+on-hear:ev *** -### `%heed` +### `%halt` ```hoon -[%heed =ship] +$>(%halt deep) ``` -A vane can pass Ames a `%heed` task to request Ames track a peer's responsiveness. If our `%boon`s to it start backing up locally, Ames will `%give` a `%clog` back to the requesting vane containing the unresponsive peer's Urbit address. +where the relevant case of [`$deep`](data-types.md#deep) is: -Stop tracking a peer by sending Ames a [`%jilt`](tasks.md#jilt) task. +```hoon +[%halt =ship agent=term =bone] +``` + +`%halt` stops a flow after we hear a remote `%flub` — that is, after the peer's +Gall has told us the destination agent will not currently accept the `$plea`. A +halted flow stops re-sending; no new timers are started for it. + +Ames also passes a `%halt` task *to Gall* in the other direction, which is how +the remote `%flub` gets emitted: Gall's `+mo-halt` gives a `%boon` carrying +`%flub` back to the `$plea` sender. -The `$ship` field specifies the peer to be tracked. +The flow's `halt` flag is set in either direction: + +- forward: Gall passes a `%flub` to Ames. +- backward: a `$plea` gets `%flub`bed over the wire. #### Returns -If the `$ship` is indeed being unresponsive, as measured by backed up `%boon`s, Ames will `%give` a `%clog` gift to the requesting vane containing the unresponsive peer's urbit address. +This task returns no gifts. *** -### `%jilt` +### `%goad` ```hoon -[%jilt =ship] +[%goad =ship] ``` -`%jilt` stops tracking a potentially unresponsive peer that was previously being tracked as a result of the [`%heed`](tasks.md#heed) task. - -There are two `+on-jilt` arms, this task utilizes `+on-hear:event-core`. +`%goad` restarts flows to `.ship` that were previously halted, once the remote +agent is live again. Halted flows do not start new timers, so a `%goad` is what +gets them moving. -The `$ship` field specifies the peer we want to stop tracking. +The `$ship` field specifies the peer whose flows should be restarted. #### Returns diff --git a/content/urbit-os/kernel/dill/data-types.md b/content/urbit-os/kernel/dill/data-types.md index 49e4c5f0..60287214 100644 --- a/content/urbit-os/kernel/dill/data-types.md +++ b/content/urbit-os/kernel/dill/data-types.md @@ -169,7 +169,7 @@ Wrapped Dill tasks. $% [%crop p=@ud] :: trim kernel state $>(%crud told) :: [%heft ~] :: - [%meld ~] :: unify memory + [%meld $@(~ [memo=? ford=?])] :: unify memory [%pack ~] :: compact memory $>(%text told) :: [%verb ~] :: verbose mode diff --git a/content/urbit-os/kernel/dill/tasks.md b/content/urbit-os/kernel/dill/tasks.md index 057f05b0..e4452a65 100644 --- a/content/urbit-os/kernel/dill/tasks.md +++ b/content/urbit-os/kernel/dill/tasks.md @@ -116,11 +116,23 @@ A `$told` is either a [`%crud`](tasks.md#crud), [`%talk`](tasks.md#talk) or [`%t Deduplicate persistent state. ```hoon -[%meld ~] +[%meld $@(~ [memo=? ford=?])] ``` Dill asks the runtime to perform the memory deduplication. +The payload may be `~`, or a pair of flags selecting caches to discard *before* +the deduplication runs: + +- `memo` - drop the persistent memo cache. +- `ford` - drop the Ford build cache. + +Dropping a cache frees whatever it held, so it can recover more memory than a +bare `%meld`, at the cost of rebuilding that cache afterwards. A bare `[%meld ~]` +still type-checks and leaves both caches intact. + +The same payload appears in Dill's `$gift` and in [`$flog`](data-types.md#flog). + #### Returns Dill does not return a gift in response to a `%meld` task. @@ -139,7 +151,7 @@ Dill asks the runtime to perform the defragmentation. #### Returns -Dill does not return a gift in response to a `%meld` task. +Dill does not return a gift in response to a `%pack` task. ***