Skip to content
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

Bring kernel docs up to date with respect to current state of syscall and delivery interfaces #2452

Open
FUDCo opened this issue Feb 17, 2021 · 2 comments
Labels
documentation Improvements or additions to documentation needs-design SwingSet package: SwingSet

Comments

@FUDCo
Copy link
Contributor

FUDCo commented Feb 17, 2021

What is the Problem Being Solved?

Over the past year+ there have been numerous changes to the vat->kernel syscall interface and the kernel->vat delivery interface. The design documentation in the SwingSet/docs directory have not kept pace with these changes and need to be resynchronized with ground truth.

@FUDCo FUDCo added documentation Improvements or additions to documentation SwingSet package: SwingSet needs-design labels Feb 17, 2021
@dckc
Copy link
Member

dckc commented May 17, 2021

What's one or two specific ways that the docs are out of date?

(for context: I'm trying to figure out if the docs in their present state have a reasonable specification of clists, since #3103 seems to expect that the reader knows how they work.)

@warner
Copy link
Member

warner commented May 18, 2021

docs/delivery.md is pretty good.. at a quick glance, the things that need updating are:

  • comms vat now has a full clist between it's "local" numberspace and the kernel-facing vrefs (previously these used the same identifier)
  • syscall.resolve now takes batches of resolutions, not a single one
  • we no longer differentiate promise resolution status into "fulfilled to object" / "fulfilled to data" / "rejected", instead we have one boolean flag for "resolved vs rejected", and capdata. The "fulfilled to object" is now just "resolved (not rejected)" along with capdata that references a single object.
  • the document could stand to talk about the VatDeliveryObject which is a data structure that encapsulates a delivery of some sort (deliver, notify, dropExports, etc), now that the vat's dispatch function is defined to take one, rather than the previous approach in which dispatch was an object and dispatch.deliver was one of its methods

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation needs-design SwingSet package: SwingSet
Projects
None yet
Development

No branches or pull requests

4 participants