Async API

[curiousdannii]

So a couple of years ago, I tried out how an async GlkOte API might work. I'd like to revisit this as an option for GlkOte itself rather than pursuing it as a fork.

So the main issue is that it's just not possible to synchronously access the filesystem on some systems which I'd be interested in bringing GlkOte to, namely cloud file hosting services like Dropbox and Google Drive, as well as mobile apps using Cordova, and even IndexedDB in the browser. But it would also give the opportunity to make the JS API simpler: rather than having the user set up callbacks and then a handler that has to distinguish whether it's a Glk even or a special event and then call the callback func, which now has a different context than the original function, an async API would let you simply call the one function you want, and get back the result in the same function context, just like the C API! So if you call glk_select you'll get back a Glk event and nothing else (ideally without even needing to call Glk.update - that should be handled internally), if you call glk_fileref_create_by_prompt you'll get back the file result without needing to worry about handling arrange events that might have occurred, etc.

The main disadvantage is that this would be a major breaking change, not just to how GlkOte is used, but it could require substantial changes to the end applications, Quixe etc. But I'd be willing to make those changes if we went forward in this direction.

So previously I guessed that too many Glk functions would need to be async. Partly this was because I thought that the glk_get_ functions might be able to pull data from the filesystem as it went. For something like Dropbox that's just not going to be feasible. Instead the Dialog system should be simplified to say that files to be read just need to be read and buffered in their entirety. (Files being written could perhaps still be periodically flushed, as feedback from that wouldn't need to be received back immediately.) So the functions I think would need to be made async would be:

• glk_fileref_create_by_prompt
• glk_fileref_does_file_exist
• glk_select
• glk_stream_open_file(_uni)

Possibly these:

• glk_exit?
• glk_fileref_delete_file? (probably not as it gives no feedback as to whether it was successful?)
• glk_image_get_info (for non-blorbed images)
• glk_select_poll (but only for symmetry)
• glk_stream_open_resource(_uni)? (probably not necessary)

I had originally included some window functions as I thought it would be better to not just assume that new windows can always be opened. I'd also included the sound channel functions, because who knows, they might need to be async? We could reconsider them later. It may be possible to shift them to async without an addition breaking change, or that could be GlkOte version 4.

[curiousdannii]

Thinking again, if we add new functions, then users of GlkApi which expect the old API could still function, just without having file support (every file call can just return a fail result). The trickiest part would be having glk_select and glk_select_async both work in one codebase. At least they wouldn't have to work at the same time!