Instead of
myemitter.emit("event", [arg1, arg2, arg3]);
the API is now
myemitter.emit("event", arg1, arg2, arg3);
This change saves the creation of an extra array object for each event.
The implementation is also slightly more simple.
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.