Update promise.coroutine.md #1428
Conversation
This is for this [issue](petkaantonov#1426) TODO: The `Promise` by the function returned by the `coroutine` method needs further explanation. A thorough understanding of [the code](https://github.com/petkaantonov/bluebird/blob/4f9093448f55ea76d5a8e090e42fe24b8e0da82c/src/generators.js#L191) is needed.
| @@ -13,7 +13,9 @@ title: Promise.coroutine | |||
| Promise.coroutine(GeneratorFunction(...arguments) generatorFunction, Object options) -> function | |||
| ``` | |||
|
|
|||
| Returns a function that can use `yield` to yield promises. Control is returned back to the generator when the yielded promise settles. This can lead to less verbose code when doing lots of sequential async calls with minimal processing in between. Requires node.js 0.12+, io.js 1.0+ or Google Chrome 40+. | |||
| In a typical use case, the parameter `generatorFunction` should be a `GeneratorFunction` producing a generator that yields one or more `Promise`s. (Also see the Tips section below.) | |||
There was a problem hiding this comment.
Nit, the generator is the function itself - it returns an iterator. So it's a GeneratorFunction but it's not producing a generator function.
Maybe: "In a typical use case, the parameter generatorFunction should be a GeneratorFunction that can yield zero or more Promises. (Also see the Tips section below.)"?
There was a problem hiding this comment.
Ah. I thought it's the generator that "yields", actually it's the GeneratorFunction, which can be seen as the "factory".
There was a problem hiding this comment.
It returns a function that when called runs the generator function. The factory here is Promise.coroutine and the generator is run exactly once per invocation (and pumped in the code).
There was a problem hiding this comment.
Just to be clear, a generator is not a GeneratorFunction, and is an "iterator" :
The Generator object is returned by a generator function and it conforms to both the iterable protocol and the iterator protocol.
| Returns a function that can use `yield` to yield promises. Control is returned back to the generator when the yielded promise settles. This can lead to less verbose code when doing lots of sequential async calls with minimal processing in between. Requires node.js 0.12+, io.js 1.0+ or Google Chrome 40+. | ||
| In a typical use case, the parameter `generatorFunction` should be a `GeneratorFunction` producing a generator that yields one or more `Promise`s. (Also see the Tips section below.) | ||
|
|
||
| This method returns a function that returns a `Promise`(TODO: Elaborate this). When the returned function (e.g. the `ping` function in the example below) is called, it will start the generator (by calling its `next()`) and return immediately. Control is returned back to the generator when each yielded promise settles. This can lead to less verbose code when doing lots of sequential async calls with minimal processing in between. Requires node.js 0.12+, io.js 1.0+ or Google Chrome 40+. |
There was a problem hiding this comment.
About the todo:
"That returns a Promise that resolves to the value returned from the generator function (if that value is a promise, it will be unwrapped)" ?
That's not entirely accurate (since a finally block can still intercept it - but I think it's accurate enough for virtually 100% of user use cases.
There was a problem hiding this comment.
- What will the promise be like when multiple values or promises are yielded?
- We can use
awaitnow, so that kind of use case will be very rare. - Also, the example didn't make use of the returned promise.
There was a problem hiding this comment.
What will the promise be like when multiple values or promises are yielded?
yielded values don't affect the return value, the promise will always be the return value.
We can use await now, so that kind of use case will be very rare.
I agree, Promise.coroutine can be used as a performance feature for code after you prove it's needed. Although @spion disagrees.
Also, the example didn't make use of the returned promise.
An example would definitely be nice here.
| @@ -52,8 +54,6 @@ Running the example: | |||
| Ping? 8 | |||
| ... | |||
|
|
|||
| When called, the coroutine function will start an instance of the generator and returns a promise for its final value. | |||
There was a problem hiding this comment.
It is replaced by "When the returned function (e.g. the ping function in the example below) is called, it will start the generator (by calling its next()) and return immediately."
|
Hey, thanks a lot for this! Left some feedback on the PR. |
|
Hey, are you going to address the feedback and finish this @luishigit ? |
|
@benjamingr Hi sorry for the delay. Now I think there should also be a summary for the purpose of this function. It returns a "coroutine", which is something can be executed "concurrently" and often, taken care of by an "event loop". The Some thing like that would be helpful. |
| Returns a function that can use `yield` to yield promises. Control is returned back to the generator when the yielded promise settles. This can lead to less verbose code when doing lots of sequential async calls with minimal processing in between. Requires node.js 0.12+, io.js 1.0+ or Google Chrome 40+. | ||
| In a typical use case, the parameter `generatorFunction` should be a `GeneratorFunction` producing a generator that yields one or more `Promise`s. (Also see the Tips section below.) | ||
|
|
||
| This method returns a function that returns a `Promise`(TODO: Elaborate this). When the returned function (e.g. the `ping` function in the example below) is called, it will start the generator (by calling its `next()`) and return immediately. Control is returned back to the generator when each yielded promise settles. This can lead to less verbose code when doing lots of sequential async calls with minimal processing in between. Requires node.js 0.12+, io.js 1.0+ or Google Chrome 40+. |
There was a problem hiding this comment.
Requires node.js 0.12+, io.js 1.0+ or Google Chrome 40+.
Could this be expanded, perhaps? It'd certainly be good to know what IE support looks like, and whether this can be supported by a polyfill, or if there's a more fundamental limitation. (In the comments on the page, I see someone who says that a polyfill enables it for IE10, but not IE9, but I see no confirmation of that)
I can dig into this, but I'm guessing someone more knowledgeable might know off-hand.
This is for this issue.
TODO: The
Promiseby the function returned by thecoroutinemethod needs further explanation. A thorough understanding of the code is needed.