Implement a Manual Event Pump API to Enable Non-Blocking Applications

[turbo]

This is a feature request to extend the OSApp API to allow external message pumping.

The goal is to allow NApp to be integrated into programs that already have their own event loop (async runtimes, game engines, etc.). This proposal would make osapp_run non-blocking and expose an API function callable by the program's main thread to manually process events.

The default would remain exactly as it works now, manual pumping would be an option. This is already partially in place for Windows, but not for other platforms.

Current Implementation

This is my understanding of the current implementation, which might be wrong (please correct me).

• All platforms (macOS, Windows, GTK) implement the same interface for OSApp, in particular they all have an osapp_run function.
• All platforms accept the flag app->with_run_loop, however it is ignored for macOS (src) and GTK (src), and for Windows it is always true and calls osgui_message_loop
• Platforms launch apps like this:
  • On Windows, there's a while loop in osapp_run that manually pumps events by calling osgui_message_loop
  • On macOS, osapp_run calls [(NSApplication*)app run];, which is a blocking call (Cocoa handles pumping internally)
  • On GTK, osapp_run calls g_application_run, which is a blocking call (GTK handles pumping internally)

Proposed changes

First, implement osgui_message_loop on all platforms:

• On Windows, this exists already, and seems to be the only implementation
• On macOS, instead of calling just [NsApp run], instead call it and then call [NSApp stop:nil]; from within the applicationDidFinishLaunching hook. This enables manual pumping. Then create a osgui_message_loop_imp function that dequeues events from [NSApp nextEventMatchingMask ...] and pumps them to [NSApp sendEvent:event];
• On GTK, instead of calling g_application_run, do the same setup, but create a osgui_message_loop_imp function that keeps calling g_main_context_iteration to cause GTK to pump events internally. This call must be made with g_main_context_iteration in non-blocking mode, otherwise the internal pump blocks until the next event.

Then, add an app->blocking flag that is TRUE by default. This flag must be respected in the osgui_message_loop_imp implementations. If it is TRUE, then the message loops need to be blocking, as is the case for Windows today (src). However, when it is FALSE, the message loop must return after processing events in the queue.

Finally, the osgui_message_loop function should be available via the public API so that in non-blocking mode, the parent program can call it.

Result

Now applications can launch NApp in two different ways:

• Blocking (default, current behavior): Call osmain, and NApp/OSApp handles the event loop - nothing changes and no code changes are required for current apps
• Non-blocking (set app->blocking to false): Call osmain, which immediately returns. The calling app then calls osgui_message_loop from its own event loop or scheduler to keep the OSApp instance alive. When it's done, it calls the terminate API to clean up.

This is how libraries like GLFW work today, and indeed I'm currently integrating NApp into an engine that has a competing event loop in the main thread. Here are details on the changes required:

• converting [NsApp run] into non-blocking calls (based directly on what GLFW does)
• converting g_application_run into non-blocking calls

All in all, these changes should not require much additional code, OSApp is almost there and the concept of a message loop function is already in place.

[frang75]

Hi @turbo!

I am very surprised by this issue. Both for the proposal itself, and for the level of detail when proposing the solution. Thank you for the time you have dedicated and your involvement in the project.

It is a necessary feature, which will open the use of NAppGUI to existing applications, with their own runLoop. A few years ago, in an early version of NAppGUI I implemented this support (Windows only) to create an experimental interface for a Rhinoceros 3D plugin. The const bool_t with_run_loop parameter of osapp_init_imp is a legacy from those times.

I'll get into this as soon as possible.

Please email me with your Discord username. We have created a server with a small community of active users, where we have several open development lines.

Thanks again, and welcome to NAppGUI

[turbo]

My Discord user is summarity (or send an invite to mail@summarity.com) 🙂.