Re: [promises] Guidance on the usage of promises for API developers
To address, jgraham's point, let's go back to just use "Run ..." style phrasing. I agree that we shouldn't mislead readers that task queuing is always necessary. Moreover, I think algorithm may be allowed to be done either synchronously or asynchronously for some cases. Maybe we could add "possibly" to mean it's not forced to be run later for such a case? How about introducing some markups such as "[Async]" and a note of detailed explanation (no need to queue a task, etc.)? Readers are guided to read the note to understand what they mean, and actually more likely to do so compared to just writing "do X asynchronously". I imagine. Not sure. 1. sync_work_A. 2. sync_work_B. 3. Let p be a newly-created promise. 4. [PossiblyAsync] possibly_async_work_S. 5. [PossiblyAsync] possibly_async_work_T. 6. [Async] async_work_X. 7. [Async] async_work_Y. 8. Return p. Right after returned from this method, we observe side effect of sync_work and may observe possibly_async_work's but not async_work's. If too noisy, modularize as Boris said ( http://lists.w3.org/Archives/Public/public-webapps/2014JanMar/0066.html).
Re: [promises] Guidance on the usage of promises for API developers
On 1/14/14 10:44 AM, Domenic Denicola wrote: So maybe we need slightly better phrasing; help appreciated. Maybe the right way to spec this is to simply use two algorithms... Algorithm A has some steps, then says to perform B asynchronously and returns a promise. B has a bunch of steps that end with resolving the promise. That avoids the issue of having steps-after-return and also avoids the issue of the steps of B needing to be indented a level and not clearly separated from the (conceptually separate) steps of A. I think the only issue with the two-algorithm setup might be http://www.whatwg.org/specs/web-apps/current-work/multipage/history.html#navigating-across-documents in which there is actually a goto from what I call B above (in http://www.whatwg.org/specs/web-apps/current-work/multipage/history.html#navigate-redirect-step ) to a step that is in A (http://www.whatwg.org/specs/web-apps/current-work/multipage/history.html#navigate-fragid-step ). I can't say that I'm terribly happy with that setup, though, so I think discouraging it in general is _not_ a bad thing. This seems like too much overhead when B is only a step or two, of course, maybe in those cases inlining it inside a "do these steps async" block is good. -Boris
Re: [promises] Guidance on the usage of promises for API developers
On 1/14/14 10:44 AM, Domenic Denicola wrote: I do want to clarify that I want to avoid explicitly queuing needless tasks, which then themselves go and perform asynchronous actions. Instead, just perform the asynchronous action, and use the promise microtask queue to the deliver the results. That's actually an interesting question. Right now, the deal with task queues is that certain operations explicitly freeze some task queues but not others. Thus the choice of task queue for a task determines what things it might end up blocking on (thing alert() and the like). What I think is really be desired in some cases is to perform the async action and when it's done insert a task into the right task queue that resolves the promise. If I understand correctly how microtasks work, in that situation the promise callbacks will be invoked as soon as the task finishes. Note that this is how I expect UAs to actually implement this under the hood, for what it's worth, since reaching across thread boundaries to resolve a promise is pretty suboptimal (suddenly need locks or whatnot), so chances are they'll pass messages that when received resolve promises... -Boris
RE: [promises] Guidance on the usage of promises for API developers
From: Boris Zbarsky > On 1/14/14 9:22 AM, Domenic Denicola wrote: >> Do you think it would be improved by nesting step 5 under "These steps will >> be run asynchronously"? > > Yes. Otherwise if there is another method that allows synchronously checking > whether a bookmark has been added I would expect such a method to return true > if called immediately after the addBookmark as specified here returns, > whereas the obvious desired behavior is for it to return false. I think I see what you are saying. I was implicitly assuming that the act of asking the user anything would be asynchronous, whereas it's important to state that. Otherwise, the side effects of adding a bookmark could be allowed to happen synchronously---even if the promise-enforced asynchrony ensures that e.g. `addBookmark.then(onAdded)` only calls `onAdded` asynchronously. In #whatwg jgraham pointed out: 09:41:58 Domenic_: Note that "will" in spec language is a statement of fact 09:43:35 So if you were to say "these steps will be run asynchronously", there would have to be text elsewhere that actually caused those steps to run So maybe we need slightly better phrasing; help appreciated. I do want to clarify that I want to avoid explicitly queuing needless tasks, which then themselves go and perform asynchronous actions. Instead, just perform the asynchronous action, and use the promise microtask queue to the deliver the results. You can see some discussion between Marcos and I on this point at [1]. [1]: https://github.com/domenic/promises-unwrapping/issues/85
Re: [promises] Guidance on the usage of promises for API developers
On 1/14/14 9:22 AM, Domenic Denicola wrote: Do you think it would be improved by nesting step 5 under "These steps will be run asynchronously"? Yes. Otherwise if there is another method that allows synchronously checking whether a bookmark has been added I would expect such a method to return true if called immediately after the addBookmark as specified here returns, whereas the obvious desired behavior is for it to return false. -Boris
RE: [promises] Guidance on the usage of promises for API developers
I like your way of phrasing it, because it does not explicitly queue a needless task. But I am not sure how generally it applies. What did you think of the addBookmark example? https://github.com/domenic/promises-unwrapping/blob/master/docs/writing-specifications-with-promises.md#addbookmark-- Do you think it would be improved by nesting step 5 under "These steps will be run asynchronously"? From: Takeshi Yoshino [mailto:tyosh...@google.com] Sent: Tuesday, January 14, 2014 08:30 To: www-...@w3.org Cc: public-webapps Subject: Re: [promises] Guidance on the usage of promises for API developers Nice writing! Both the shorthand phrases and guidance look very useful for writing Promise based specs. I have only one comment on this section. https://github.com/domenic/promises-unwrapping/blob/master/docs/writing-specifications-with-promises.md#maintain-a-normal-control-flow I agree with your point in the first paragraph, but the suggested way looks rather confusing. The asynchronous operation abstracted by Promises is well described, but selling this convention (writing what usually happens later before return without any annotation) to everywhere sounds too much, I think. It's good to move "Return p" to the end of the steps. But how about also keeping "do blah asynchronously" text? 1. Let p be a newly-created promise. 2. These steps will be run asynchronously. 1. If blah, reject p with undefined. 2. If blah, resolve p with foobar. 3. Return p. Thanks
Re: [promises] Guidance on the usage of promises for API developers
Nice writing! Both the shorthand phrases and guidance look very useful for writing Promise based specs. I have only one comment on this section. https://github.com/domenic/promises-unwrapping/blob/master/docs/writing-specifications-with-promises.md#maintain-a-normal-control-flow I agree with your point in the first paragraph, but the suggested way looks rather confusing. The asynchronous operation abstracted by Promises is well described, but selling this convention (writing what usually happens later before return without any annotation) to everywhere sounds too much, I think. It's good to move "Return p" to the end of the steps. But how about also keeping "do blah asynchronously" text? 1. Let p be a newly-created promise. 2. These steps will be run asynchronously. 1. If blah, reject p with undefined. 2. If blah, resolve p with foobar. 3. Return p. Thanks
[promises] Guidance on the usage of promises for API developers
FYI. (If you want to followup, please reply on www-tag @ w3.org) Original Message Subject:Guidance on the usage of promises for API developers Resent-Date:Mon, 13 Jan 2014 22:50:19 + Resent-From: Date: Mon, 13 Jan 2014 22:49:30 + From: ext Domenic Denicola To: www-...@w3.org In the past, the TAG has discussed producing a document on how to use promises in spec text. There's even a placeholder on GitHub [1]. In the process of writing the ES6 promises spec, I ended up producing such a document myself [2]. It feels like an OK start to me, with some great feedback from Marcos incorporated a month ago. I'd be happy to push this document forward as a more official TAG work product. Presumably we'd move it to its own repository and all that. But first, I'd love to solicit feedback from spec authors and readers on what's currently there, and what you think should be there. Is it clear? Is it useful? For those writing specs using promises, have they found its guidance helpful, or have they found other tips that would be good to include? Several of the "guidance" points were drawn from finding mistakes in existing drafts that use promises; are there more drafts we should review? Feedback much appreciated, either here, or as an issue on the spec repository where the document currently lives [3]. (Note that I'm mostly concerned with content for now; we can worry about formatting later.) [1]: https://github.com/w3ctag/promises-spec-text [2]: https://github.com/domenic/promises-unwrapping/blob/master/docs/writing-specifications-with-promises.md [3]: https://github.com/domenic/promises-unwrapping/issues/new
[Bug 24268] [imports]: Imported documents should obey CSP on master document.
https://www.w3.org/Bugs/Public/show_bug.cgi?id=24268 Morrita Hajime changed: What|Removed |Added Status|NEW |RESOLVED Resolution|--- |FIXED --- Comment #1 from Morrita Hajime --- https://github.com/w3c/webcomponents/commit/36c2c8298fec5e40a60716d024d52f5d72adc20d -- You are receiving this mail because: You are on the CC list for the bug.
[Bug 24288] [Shadow]: Revert element as a function call feature.
https://www.w3.org/Bugs/Public/show_bug.cgi?id=24288 Hayato Ito changed: What|Removed |Added Status|NEW |RESOLVED Resolution|--- |FIXED --- Comment #1 from Hayato Ito --- Committed in: https://github.com/w3c/webcomponents/commit/61745e0b40c8d609ad1070e7babc7915fca637ea -- You are receiving this mail because: You are on the CC list for the bug.
