document Promise temporality and VowTools #10141

turadg · 2024-09-24T18:07:22Z

incidental

Description

Document VowTools and also the kinds of Promises that one has to keep in mind when working with durable promises (vows).

Security Considerations

none

Scaling Considerations

none

Documentation Considerations

We might point to this reference material from docs.agoric.com

Testing Considerations

n/a

Upgrade Considerations

n/a

cloudflare-workers-and-pages · 2024-09-24T18:07:25Z

Deploying agoric-sdk with Cloudflare Pages

Latest commit:	`392795f`
Status:	✅ Deploy successful!
Preview URL:	https://811bbe09.agoric-sdk.pages.dev
Branch Preview URL:	https://ta-await-when.agoric-sdk.pages.dev

View logs

dckc · 2024-09-24T18:18:26Z

packages/vow/src/tools.js

+ */
+
+/**
+ * @typedef VowTools


The formatting here looks kinda dense, so I looked for a typedoc rendering at https://ta-await-when.agoric-sdk.pages.dev/modules/_agoric_vow but I don't see one. hm.

I'll clean this up in a future PR that moves them into a .ts

dckc · 2024-09-24T18:22:27Z

packages/SwingSet/docs/async.md

+When working with SwingSet, it's crucial to understand how asynchronous operations interact with the system's execution model. A **vat** (a unit of isolated execution in SwingSet) may restart or terminate before an asynchronous operation completes. Although JavaScript's `await` keyword allows you to write asynchronous code that resembles synchronous code, you must be mindful of events that could prevent a promise from settling:
+
+- **Underlying condition never satisfied**: The condition required for the promise to resolve may never occur.
+- **Vat restarts or upgrades before settlement**: The promise may be severed if the vat restarts or upgrades before it settles.


"the vat" is sort of ambiguous - there are typically 2 vats in question: the vat that exports a promise and the one that subscribes to it.

In some cases there's just 1 vat - promises that aren't exported. But those are sort of uninteresting here.

It's also possible to have more than 1 subscriber, so in general, there are N>=1 vats involved.

While I agree there are in general 2 (or more) parties involved in a promise, and either can upgrade, I believe this document is squarely on the side of the "decider" of the promise. Aka I don't believe we care much about handling disconnected promises here. Maybe we can make that more clear.

dckc

Very useful stuff to have documented!

packages/SwingSet/docs/async.md

gibson042

I like the promise classifications.

packages/SwingSet/docs/async.md

mhofman

Since this is a SwingSet doc, it's a little tricky to explain "Prompt" as it assumes some behavior of the host (cosmic-swingset in our case) to not inject I/O before quiescence, and for the APIs triggering vat upgrades to be directly driven by I/O without previous involvement of the vat getting upgraded (a fun example of that would be upgrading the bootstrap vat through core-eval, as it's the bootstrap vat that processes core eval messages)

packages/SwingSet/docs/async.md

mhofman · 2024-09-25T01:17:38Z

packages/SwingSet/docs/async.md

+When working with SwingSet, it's crucial to understand how asynchronous operations interact with the system's execution model. A **vat** (a unit of isolated execution in SwingSet) may restart or terminate before an asynchronous operation completes. Although JavaScript's `await` keyword allows you to write asynchronous code that resembles synchronous code, you must be mindful of events that could prevent a promise from settling:
+
+- **Underlying condition never satisfied**: The condition required for the promise to resolve may never occur.
+- **Vat restarts or upgrades before settlement**: The promise may be severed if the vat restarts or upgrades before it settles.


While I agree there are in general 2 (or more) parties involved in a promise, and either can upgrade, I believe this document is squarely on the side of the "decider" of the promise. Aka I don't believe we care much about handling disconnected promises here. Maybe we can make that more clear.

packages/SwingSet/docs/async.md

mhofman

Going over the prompt promise details again, I realized we could better explain the interactions between the host and swingset. Sorry for the churn.

mhofman · 2024-09-25T22:37:45Z

packages/vow/src/tools.js

@@ -34,6 +64,7 @@ export const prepareBasicVowTools = (zone, powers = {}) => {
  const watchUtils = makeWatchUtils();
  const asVow = makeAsVow(makeVowKit);

+  // DONOTMERGE this needs an issue!


Reminder to yourself :)

packages/SwingSet/docs/async.md

turadg · 2024-09-26T16:04:10Z

I force pushed to cleanup commits, thinking this had been approved. Requesting another round of review…

michaelfig

LGTM!

Only adopt my suggestions if you really want to... this nitpicking likely has diminishing returns. 😉

michaelfig · 2024-09-26T16:42:26Z

packages/SwingSet/docs/async.md

+
+When working with SwingSet, it's crucial to understand how asynchronous operations interact with the system's execution model. A **vat** (a unit of isolated execution in SwingSet) may restart or terminate before an asynchronous operation completes. Although JavaScript's `await` keyword allows you to write asynchronous code that resembles synchronous code, you must be mindful of events that could prevent a promise from settling:
+
+- **Underlying condition never satisfied**: The condition required for the promise to resolve may never occur.


Suggested change

- **Underlying condition never satisfied**: The condition required for the promise to resolve may never occur.

- **Underlying condition never satisfied**: The condition required for the promise to settle may never occur.

michaelfig · 2024-09-26T16:42:40Z

packages/SwingSet/docs/async.md

+- **Prompt Promises**:
+  - **Settlement**: Before any new I/O occurs, possibly over multiple cranks.
+  - **Dependencies**: No external input required, but may involve inter-vat asynchronous operations.
+  - **Example**: Internal message passing between vats that resolves before any new external events.


Suggested change

- **Example**: Internal message passing between vats that resolves before any new external events.

- **Example**: Internal message passing between vats that settles before any new external events.

michaelfig · 2024-09-26T16:43:04Z

packages/SwingSet/docs/async.md

+
+Understanding the temporality of promises in SwingSet helps you write robust asynchronous code that behaves predictably, even in the face of vat restarts, upgrades, or terminations. By being aware of the differences between Immediate, Prompt, and Delayed promises, you can design your smart contracts and applications to be more resilient and efficient.
+
+- **Immediate Promises** are resolved within the same crank and are safe from vat restarts or upgrades during that crank.


Suggested change

- **Immediate Promises** are resolved within the same crank and are safe from vat restarts or upgrades during that crank.

- **Immediate Promises** are settled within the same crank and are safe from vat restarts or upgrades during that crank.

michaelfig · 2024-09-26T16:45:33Z

packages/SwingSet/docs/async.md

+
+## Immediate Promises
+
+An **Immediate** promise is one that settles within the same Crank as its creation (see [Kernel Cycles](./state.md)). We refer to this as "Immediate" because it occurs before any further message deliveries into the vat, similar to how promise reaction callbacks happen before `setImmediate` callbacks in JavaScript.


Suggested change

An **Immediate** promise is one that settles within the same Crank as its creation (see [Kernel Cycles](./state.md)). We refer to this as "Immediate" because it occurs before any further message deliveries into the vat, similar to how promise reaction callbacks happen before `setImmediate` callbacks in JavaScript.

An **Immediate** promise is one that settles within the same Crank as its creation (see [Kernel Cycles](./state.md)). We refer to this as "Immediate" because it occurs before any further message deliveries into the vat, similar to how all promise reaction callbacks happen before any JavaScript event callbacks (such as those queued by `setImmediate`).

mhofman

LGTM. I would consider the clarification around resolve/settle worthwhile.

Co-authored-by: Richard Gibson <richard.gibson@gmail.com> Co-authored-by: Mathieu Hofman <86499+mhofman@users.noreply.github.com> Co-authored-by: Michael FIG <mfig@agoric.com>

turadg requested review from warner, mhofman and michaelfig September 24, 2024 18:09

dckc reviewed Sep 24, 2024

View reviewed changes

packages/SwingSet/docs/async.md Outdated Show resolved Hide resolved

packages/SwingSet/docs/async.md Outdated Show resolved Hide resolved

gibson042 reviewed Sep 24, 2024

View reviewed changes

packages/SwingSet/docs/async.md Outdated Show resolved Hide resolved

packages/SwingSet/docs/async.md Outdated Show resolved Hide resolved

packages/SwingSet/docs/async.md Outdated Show resolved Hide resolved

packages/SwingSet/docs/async.md Outdated Show resolved Hide resolved

mhofman reviewed Sep 25, 2024

View reviewed changes

turadg marked this pull request as ready for review September 25, 2024 21:18

turadg requested review from gibson042 and mhofman September 25, 2024 22:21

mhofman reviewed Sep 25, 2024

View reviewed changes

docs: VowTools

b81bba9

turadg force-pushed the ta/await-when branch from 593292d to 3ad1a1d Compare September 26, 2024 16:03

turadg requested a review from a team as a code owner September 26, 2024 16:03

turadg requested a review from mhofman September 26, 2024 16:04

michaelfig approved these changes Sep 26, 2024

View reviewed changes

mhofman approved these changes Sep 26, 2024

View reviewed changes

docs: Immediate, Prompt and Delayed promises

392795f

Co-authored-by: Richard Gibson <richard.gibson@gmail.com> Co-authored-by: Mathieu Hofman <86499+mhofman@users.noreply.github.com> Co-authored-by: Michael FIG <mfig@agoric.com>

turadg force-pushed the ta/await-when branch from 3ad1a1d to 392795f Compare September 26, 2024 21:54

turadg added automerge:rebase Automatically rebase updates, then merge bypass:integration Prevent integration tests from running on PR labels Sep 26, 2024

mergify bot merged commit 0b1501a into master Sep 26, 2024
92 of 97 checks passed

mergify bot deleted the ta/await-when branch September 26, 2024 22:10

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

document Promise temporality and VowTools #10141

document Promise temporality and VowTools #10141

turadg commented Sep 24, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Sep 24, 2024 •

edited

Loading

dckc Sep 24, 2024

turadg Sep 25, 2024

dckc Sep 24, 2024

mhofman Sep 25, 2024

dckc left a comment

gibson042 left a comment

mhofman left a comment

mhofman Sep 25, 2024

mhofman left a comment

mhofman Sep 25, 2024

turadg commented Sep 26, 2024

michaelfig left a comment

michaelfig Sep 26, 2024

michaelfig Sep 26, 2024

michaelfig Sep 26, 2024

michaelfig Sep 26, 2024

mhofman left a comment


		When working with SwingSet, it's crucial to understand how asynchronous operations interact with the system's execution model. A vat (a unit of isolated execution in SwingSet) may restart or terminate before an asynchronous operation completes. Although JavaScript's `await` keyword allows you to write asynchronous code that resembles synchronous code, you must be mindful of events that could prevent a promise from settling:

		- Underlying condition never satisfied: The condition required for the promise to resolve may never occur.

	- Example: Internal message passing between vats that resolves before any new external events.
	- Example: Internal message passing between vats that settles before any new external events.


		Understanding the temporality of promises in SwingSet helps you write robust asynchronous code that behaves predictably, even in the face of vat restarts, upgrades, or terminations. By being aware of the differences between Immediate, Prompt, and Delayed promises, you can design your smart contracts and applications to be more resilient and efficient.

		- Immediate Promises are resolved within the same crank and are safe from vat restarts or upgrades during that crank.

	- Immediate Promises are resolved within the same crank and are safe from vat restarts or upgrades during that crank.
	- Immediate Promises are settled within the same crank and are safe from vat restarts or upgrades during that crank.


		## Immediate Promises

		An Immediate promise is one that settles within the same Crank as its creation (see [Kernel Cycles](./state.md)). We refer to this as "Immediate" because it occurs before any further message deliveries into the vat, similar to how promise reaction callbacks happen before `setImmediate` callbacks in JavaScript.

document Promise temporality and VowTools #10141

document Promise temporality and VowTools #10141

Conversation

turadg commented Sep 24, 2024 • edited Loading

Description

Security Considerations

Scaling Considerations

Documentation Considerations

Testing Considerations

Upgrade Considerations

cloudflare-workers-and-pages bot commented Sep 24, 2024 • edited Loading

Deploying agoric-sdk with Cloudflare Pages

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dckc left a comment

Choose a reason for hiding this comment

gibson042 left a comment

Choose a reason for hiding this comment

mhofman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mhofman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

turadg commented Sep 26, 2024

michaelfig left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mhofman left a comment

Choose a reason for hiding this comment

turadg commented Sep 24, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Sep 24, 2024 •

edited

Loading