-
Notifications
You must be signed in to change notification settings - Fork 214
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
document Promise temporality and VowTools #10141
Conversation
Deploying agoric-sdk with Cloudflare Pages
|
*/ | ||
|
||
/** | ||
* @typedef VowTools |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll clean this up in a future PR that moves them into a .ts
packages/SwingSet/docs/async.md
Outdated
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Very useful stuff to have documented!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I like the promise classifications.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
Outdated
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Going over the prompt promise details again, I realized we could better explain the interactions between the host and swingset. Sorry for the churn.
packages/vow/src/tools.js
Outdated
@@ -34,6 +64,7 @@ export const prepareBasicVowTools = (zone, powers = {}) => { | |||
const watchUtils = makeWatchUtils(); | |||
const asVow = makeAsVow(makeVowKit); | |||
|
|||
// DONOTMERGE this needs an issue! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reminder to yourself :)
593292d
to
3ad1a1d
Compare
I force pushed to cleanup commits, thinking this had been approved. Requesting another round of review… |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM!
Only adopt my suggestions if you really want to... this nitpicking likely has diminishing returns. 😉
packages/SwingSet/docs/async.md
Outdated
|
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- **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. |
packages/SwingSet/docs/async.md
Outdated
- **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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- **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. |
packages/SwingSet/docs/async.md
Outdated
|
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- **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. |
packages/SwingSet/docs/async.md
Outdated
|
||
## 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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`). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM. I would consider the clarification around resolve/settle worthwhile.
Co-authored-by: Richard Gibson <[email protected]> Co-authored-by: Mathieu Hofman <[email protected]> Co-authored-by: Michael FIG <[email protected]>
3ad1a1d
to
392795f
Compare
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