Skip to content

Document main actor execution in Java hosts #956

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ktoso merged 1 commit into from
Nov 7, 2026
Merged

Document main actor execution in Java hosts #956

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,8 @@ In this mode the generated sources use JNI to call native code.
This mode offers less performance and flexibility than FFM, but it is the most compatible: it works on older JVMs as well as on Android.
Use it when FFM is not available, or when wide deployment compatibility is your priority. When performance is paramount, prefer FFM.

For Android-specific guidance, see also the [Android documentation](Sources/SwiftJavaDocumentation/Documentation.docc/Android.md).

Required language/runtime versions:
- **Swift 6.2**, because of dependence on rich swift interface files
- **JDK 17+**; the generated Java sources target the `javaSourceLevel` setting, which supports 17 through 25 (default 22)
Expand Down
12 changes: 12 additions & 0 deletions Sources/SwiftJavaDocumentation/Documentation.docc/Android.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,18 @@ Hints and patterns for using swift-java on Android.

## Overview

### Main actor and the UI thread

When using Swift from an Android app, work submitted to Swift's main executor
is not executed by default, so integration with the host environment is needed.
Without it, asynchronous work that switches to the main actor may stop making
progress. This applies both to public Swift APIs called directly from Java and
to uses of the main actor inside a Swift library.

The [swift-android-native](https://github.com/swift-android-sdk/swift-android-native/tree/main#running-work-on-the-android-main-thread)
implementation is one example of this integration. It can run Swift's main
actor on Android's UI thread.

### R8/Proguard Rules

Since swift-java uses JNI and reflection APIs, the R8 optimizer must be told to keep the wrapped types.
Expand Down
10 changes: 10 additions & 0 deletions Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaJextract.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,16 @@ public final class SomeModule ... {
}
```

### Main actor in Java-hosted processes

Swift libraries may use the main actor in their public APIs or internally.
When calling Swift from a Java-hosted process, you may need to integrate
Swift's main executor with the host's event loop.

Without appropriate integration, work scheduled on the main actor may not
execute, leaving asynchronous calls incomplete. The required integration
varies by platform and host configuration. For Android, see <doc:Android>.

## See Also

- <doc:FeaturesJextract>
Expand Down
Loading