Add a returning promises section

[marcoscaceres]

Interesting discussion came up internally at Mozilla around what should happen when you have a .method() that returns a promise. We were discussing annotating methods with [NewObject] for promise returning .method()... question that came up was, should a promise returning method always return a newly created promise? Or are there cases where it makes sense to return the same Promise, representing some ongoing operation.

For example:

const p1 = Tasks.doTask("some-id");
const p2 = Tasks.doTask("some-id"); 

await Promise.all([p1, p2]);
const p3 = Tasks.doTask("some-id"); // obviously a new promise!

As p1 and p2 represent the same task, would p1 === p2 or p1 !== p2? My personal preference is for always getting new promises object, but some guidance would be great.

[plinss]

It's an interesting question, but if the returned promises resolve to the same object, what would the purpose of creating new promises be?

In other words, given:

const p1 = Tasks.doTask("some-id");
const p2 = Tasks.doTask("some-id"):
const t1 = await p1;
const t2 = await p2:

If t1 === t2 then why p1 !== p2? It seems like you'd just be creating implementation complexity for no benefit, or is there a benefit I'm missing? Obviously if t1 !== t2 then p1 !== p2 must be true as well.

[domenic]

// obviously a new promise!

This doesn't seem obvious to me. It depends on the semantics of Tasks.doTask().

[marcoscaceres]

This doesn't seem obvious to me. It depends on the semantics of Tasks.doTask().

Yeah, in retrospect, you are right. It's not obvious.