Problem

swift-java can export asynchronous Swift functions annotated with @MainActor to Java. However, depending on the host environment, a call may stop making progress when it switches to the main actor. This can happen not only when the exported function is itself annotated with @MainActor, but also when a Swift library uses the main actor internally.

It is natural for swift-java users to expect @MainActor, a standard Swift language feature, to work as usual. As a result, they may not immediately recognize the cause of the problem. The issue is also technically complex, making it difficult for many users to address.

For an example, see:

• [Android] MainActor / DispatchQueue.main work is not drained in JNI-backed Android app process swift#89711

Technical background

This problem occurs when work submitted to Swift's main executor is not executed in the host environment.

When a Swift executable is launched, its entry point and platform environment are responsible for running asynchronous work and event loops. In contrast, when a Java application calls Swift, the Java host manages the process entry point and event loop. swift-java generates bindings for Swift libraries used in that process. Depending on the host environment, additional integration may therefore be needed to run Swift's main executor.

For example, swift-android-native provides an implementation that uses the private libdispatch API _dispatch_main_queue_callback_4CF to process the Dispatch main queue used by Swift's main executor on the Android main looper.

Proposal

Ideally, users should be able to use Swift code that relies on @MainActor without additional effort. However, swift-java does not own the host process's entry point or event loop, and the necessary integration depends on the host environment and application configuration.

As a first step, I propose updating the documentation so that users can discover this limitation and understand that host-side integration may be needed. I am preparing a PR for the documentation update.

Future directions

In the future, it may be worth considering whether swift-java should provide an implementation to run the main executor. For example, one possibility would be to start a dedicated thread at JNI_OnLoad to drive the Swift main executor.