Add E.get(x) documentation

[danfinlay]

This module is full of one-letter methods, and combined with no docs, it is very hard to dive into.

I may document this as I go, because I'm gradually chipping in, but opening an issue in case someone wants to quickly type up an answer key before I have to deduce it from source.

Some mysterious letters that I'm trying to decode:

• E() itself, which I think basically just lines up methods on the eventual result, but potentially remotely, using some messaging format?
• E.C(presence)
• E.C(presence).G
• E.C(presence.G[objectKey].M[methodName]
• E.C(presence).G[promiseKey].P

I'm also unclear to what degree pipelining works now. This issue suggests it is not added yet, but some aspect of it was merged soon after.

Some notes on how I'm testing capTP

As a very simple test, I'm experimenting whether I can send a message that says to a pizzeria presence "whatIsLargestPizzaSize().then(orderPizzaBySize)". This should be doable with a single round trip, and so that is my basic benchmark for the feature.

More realistically, I would want to ask pizzeria.getSizeList().then(pickLargestOption).then(orderPizza), where pickLargestOption could be a user-specified algorithm, which might require the .there() call that Mark described to me.

Anyways, once I get a deeper understanding here, I may contribute some of these features here instead of at capnode, if I can just get the developer ergonomics up to where I'd feel comfortable promoting them.

[danfinlay]

My basic pizza example is started here.

[danfinlay]

Couldn't help but read a little further (though Michael mentioned he's catch me up soon, probably tomorrow). Found the relevant file:

  E.G = o => makeEGetterProxy(o);
  E.H = o => makeEHasProxy(o);
  E.D = o => makeEDeleterProxy(o);
  E.S = o => makeESetterProxy(o);
  E.M = o => makeEMethodProxy(o);
  E.C = EChain;

Reading the implementation of makeHandledPromise, which is used to initialize E, I think I'm getting it:

These are all internal methods for E()-generated HandledPromise objects, which support chaining these additional getters/setters/deleters chained to the pending object.

Those are then converted to internal handle calls, which is I guess where the pipelining would really need to come into play? It seems like handle needs to be keeping a message queue per HandledPromise?

[michaelfig]

You got it!

Just one thing: the handle calls don't need to queue anything if you specify an unfulfilledHandler (second argument to currently Promise.makeHandled, eventually new HandledPromise). They do queue (but don't pipeline) if you leave off the second argument, until the promise resolves.

captp registers handlers for GET and POST, enabling pipelining of those property gets/method/function calls because its unfulfilledHandler just fires off the appropriate message to the remote destination.

[michaelfig]

So the main things I need to document:

1. E(x).method(arg) === E.M(x).method(arg) and returns a pipelineable promise for the result of a remote method call on x.
2. E.G(x).prop returns a pipelineable promise for a remote property-get on x.
3. E.C is much weirder. It is only useful if you find yourself getting lost in the left-hand nesting of the above calls and really want to use a fluent API.

const p1 = E.G(E(E(y).method(arg)).method2(arg2)).prop;
// is equivalent to:
const p2 = E.C(y)
  .M.method(arg)
  .M.method2(arg2)
  .G.prop
  .P;
// and is read:
// Eventual Chain of `y`,
// to Method call "method(arg)",
// to Method call "method2(arg2)",
// to Get "prop",
// to Promise

E.C was an experiment.

[erights]

Be careful how you make the analogy to (await x).method(arg) because they are very not equivalent. This analogy may be more confusing that it is worth. I suggest just showing the local behavior

Promise.resolve(x).then(t => t.method(args))

instead. Likewise for the others.

[tyg]

As of 2021-2-18, per Michael only E(x) and E.G(x) are still implemented. So this is changed/reduced to adding something about E.G(x) to the section in distributed-programming about E(x).

[tyg]

As of 2021-22-02, this is under discussion in agoric-sdk issue #2502. Work on this pending decisions made there.

[tyg]

Final decision is to add E.get(x), formerly E.G(x) only.

[danfinlay]

That sounds like a very easy to interpret alias!

[Tyrosine22]

I suspect this bug is no longer relevant, but I need to ping one of the commenters above to make sure.

[dckc]

We now have reference docs for E.get() .

It's not integrated with docs.agoric.com yet, though.