Re: miniSphere 5.0b3 (stable: 4.8.8)
Reply #2149 –
API design is a very subtle art and it's been my experience that method naming isn't always just about the immediate effect of a method. Consider the difference between:
Sphere.exit();
Dispatch.onUpdate(doStuff);
Versus:
Sphere.shutDown()
Dispatch.onUpdate(doStuff);
One might reasonably expect the former to close the engine regardless of what comes after. It wouldn't, because the new job added to Dispatch keeps the event loop alive. "But I explicitly said to exit, what's going on?!" Whereas, if one looks at the latter code, it's requested a shutdown, but then added a new process afterwards which effectively cancels the request (you can't shut down if there are active processes). It makes more sense intuitively that a request to "shut down" would be canceled (since an OS shutdown can do this too), canceling an "exit" (which sounds atomic) seems nonsensical.
Consider the documentation for
ExitMapEngine(), where the note laying out the caveat is significantly longer than the description of the API:
https://github.com/sphere-group/sphere/blob/master/sphere/docs/development/api.txt#L495-L499And that note is *STILL* vague--what exactly causes MapEngine to return if not the exit call itself? I know the answer to that because I'm familiar with the Sphere 1.x source code and know that it's single-threaded. But to the uninitiated it's not nearly as obvious. For example if you start a FlipScreen loop in an update script that will block the exit despite performing other event loop-y operations. Which is why the miniSphere documentation is much more explicit about it:
https://github.com/fatcerberus/minisphere/blob/master/docs/sphere2-core-api.txt#L236-L240Control MUST return to the engine (i.e. ongoing JavaScript operations must run to completion) for the request to be honored.