The problem was that if promise A was waiting and promise B was created and
then also told to wait (from some callback coming off the event loop), and
then promise A finished, promise B's wait would return. Promise A's wait
would not return until promise B was finished. This is incorrect.
To solve this issue properly, one probably needs to allocate separate
execution stacks. I use, instead, Poor Man's Coroutines. We continue to use
the main execution stack and force promises created most recently to return
first.
That is even if Promise A finishes first, neither wait() returns. Not until
Promise B finishes, will its wait() return. After that is complete, Promise
A's wait() will return.
This introduces the problem of growing the "wait stack" infinitely. Thus
I've added a strong warning to the documentation only to use this operation
sparingly. require() and include() seem to be the proper use case for such a
thing: they are called usually at program start up - they don't take too
long to finish and they won't be called so often.
Let's experiment with this stop-gap. If the infinite promise stack becomes a
problem for many, then I will remove promise.wait() entirely or perhaps only
use it for thread pool events.
`include` and `require now` call `promise.wait` on their retrieval functions
making them synchronous. Introduce `include_async` and `require_async` to
do asynchronous retrievals.
`include_async` and `require_async` need testing and documentation.
Update documentation for include, require(). I am mostly removing
information about onLoad(). onLoad is to be depreciated.
promise.wait() now returns the arguments of the "success" event. If there
was only a single argument, then it is returned. If there was more than
one, they are returned as an array. If there was an error, it is thrown.
See documentation.
With the addition of non-libeio stdio (17c6a67f15)
this class is no longer being used internally. It has proved buggy and isn't
full-featured enough to be very useful. Since it's implemented entirely in
javascript it will be easy for someone to extra into their own library if
needed.
