Document main actor execution requirements in Java-hosted processes

Open Beginner friendly
  • Is something wrong?
#955 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
76/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
java, swift
Domain
documentation

Research direction

Find the documentation covering asynchronous Swift APIs and Java-hosted processes; the issue does not name a specific file, so first locate the relevant documentation entry point. Explain that calls relying on Swift's main executor may stop making progress depending on the host environment, and that host-side integration may be required. Done when users can discover this limitation and understand why it occurs.

Written by the indexing model from the issue text.

Description

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:

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.

Dominant language
Swift
Stars
1.3k
Forks
127
Avg merge
1h 6m
Merged PRs (30d)
3

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from swiftlang/swift-java

All issues in swiftlang/swift-java

Similar issues

More Swift issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.