docs: a set of diagrams on Zoe and Zcf datastores and initialization #6389
Conversation
refs: #4383 The datastore diagram was created in Miro: https://miro.com/app/board/uXjVPR6j4Nc=/?share_link_id=559329933746 The others are .puml rendered to png. These diagrams show the state of Zoe and ZCF as of 2022/10/1. I expect to update them as I finish the conversion to durability. The datastore diagram shows which objects and stores are accessible to Zoe or to ZCF, and which are shared. The sequence diagrams show the order in which the various objects are created, passed between the vats, and when promises are resolved.
Chris-Hibbert
added
documentation
There was a problem hiding this comment.
Every time I see one of these diagrams I wish we could also have arrows that slope downward, i.e., where the arrowhead is below the arrowtail. Then we could use the horizontal lines only for synchronous intravat calls and the diagonal lines for eventual sends. Though if I did get my wish, I'd then want to be able to chain the diagonals to reflect promise pipelining ;)
No change yet suggested. Just venting.
There was a problem hiding this comment.
On the miro diagram, are your arrow directions consistent? Specifically the arrow connecting a far object to its remote presence. For the zoe service, the arrow points from the service to its remote presence, which seems weird to me. For the InvitationMaker, it points from the remote presence to the far object it designates, which makes sense to me.
There was a problem hiding this comment.
miro diagram: perhaps add to legend in the lower left what a cylinder means?
As you probably already know, I really like the stacked rectangles to represent multiple instantiation. It also like seeing these stacked within their maker function, so that spatial containment reflects lexical scope. Just graphically, stacked cylinders look weird, but I have no better suggestion. No change suggested unless you think of something better.
There was a problem hiding this comment.
Does the "Zoe startup" slide illustrate only what happens in the first crank? Is it intended to cover all of the first crank?
When you go for full upgradability, it will be interesting to see if you need different diagrams for the initial vs the revivify cases. (Hoping not, of course)
In governance/docs/gen.sh, there's a script that can do that. In this case, I generated the .png files from VSCode directly.
I'll copy gen.sh and make it mechanical. |
Fixed. |
MIro truncates the text with margins, so I have to manually shrink/stretch the boxes or change font sizes. Eternal vigilance is the only solution I know of. |
Good point. I moved it outside. |
I put the already-started legend in a box and added cylinders and tables. |
|
Have you pushed these changes yet? |
I wasn't thinking about that distinction. I think the answer is that this all happens during the first crank, but I was only looking at data stores. I'll see whether anything else interesting happens. |
No. Usually I'd add all these responses before pushing them all at once with the new commit. Since your comments were all top-level, I couldn't reply to them directly, and AFAICT, I can only have one top-level comment open at a time. Perhaps I should have replied in one long scroll, which would have made it possible to not release them until I was done. |
Oops! that's just an extra copy. I'll drop one. |
|
Okay, I pushed those changes. |
No worries. Now that I know, the way you replied was fine. I will also sometimes reply to a comment based on not-yet-pushed state. |
There was a problem hiding this comment.
These diagrams gave me the great pleasure of seeing how things I already "know" become visual. I did not see any discrepancies against my memory of what I know. Since this is just documentation that'll be revised anyway as you proceed with zoe-upgrade, I did not check it against the actual code, only my memories. I'm happy to see this merge on that basis.
LGTM
…6389) * docs: a set of diagrams on Zoe and Zcf datastores and initialization refs: #4383 The datastore diagram was created in Miro: https://miro.com/app/board/uXjVPR6j4Nc=/?share_link_id=559329933746 The others are .puml rendered to png. These diagrams show the state of Zoe and ZCF as of 2022/10/1. I expect to update them as I finish the conversion to durability. The datastore diagram shows which objects and stores are accessible to Zoe or to ZCF, and which are shared. The sequence diagrams show the order in which the various objects are created, passed between the vats, and when promises are resolved. * docs: updates to Zoe-ZCF dataStores miro diagram Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
refs: #4383
Description
The datastore diagram was created in Miro:
https://miro.com/app/board/uXjVPR6j4Nc=/?share_link_id=559329933746
The others are .puml rendered to png.
These diagrams show the state of Zoe and ZCF as of 2022/10/1. I expect to update them as I finish the conversion to durability.
The datastore diagram shows which objects and stores are accessible to Zoe or to ZCF, and which are shared.
The sequence diagrams show the order in which the various objects are created, passed between the vats, and when promises are resolved.
Security Considerations
Making the design understandable
Documentation Considerations
Yes
Testing Considerations
None.