Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
37 changes: 26 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,13 +24,18 @@ your iOS and Android code calls as if it were local.

## How it works

| | iOS | Android |
|---|---|---|
| JVM | Zero (jdk-mobile's interpreter: iOS forbids JIT) | HotSpot server VM (C2 JIT) |
| Where | Linked into the app (`libjvm.a`, static) | `libnja.so`: HotSpot + the JDK's natives + the bridge, loaded by ART |
| Calls | JNI from the calling Kotlin/Native thread (attached on first use, detached when it ends) | Handed from the ART thread to a HotSpot thread paired with it (futex channel, spin-then-sleep) |
| Callbacks (JVM → app) | JNI upcall on the same thread | The answer of the channel, served on the ART thread; nested calls recurse on the same pair |
| Fallback process | none | none |
| | iOS | Android | JVM (desktop) |
|---|---|---|---|
| JVM | Zero (jdk-mobile's interpreter: iOS forbids JIT) | HotSpot server VM (C2 JIT) | The app's own |
| Where | Linked into the app (`libjvm.a`, static) | `libnja.so`: HotSpot + the JDK's natives + the bridge, loaded by ART | The façades on the app's class path |
| Calls | JNI from the calling Kotlin/Native thread (attached on first use, detached when it ends) | Handed from the ART thread to a HotSpot thread paired with it (futex channel, spin-then-sleep) | A plain call into the dispatcher, on the calling thread |
| Callbacks (JVM → app) | JNI upcall on the same thread | The answer of the channel, served on the ART thread; nested calls recurse on the same pair | A plain call back, on the same thread |
| Fallback process | none | none | none |

**A JVM target** (`jvm()`, a desktop app) sees the same proxies as the mobile ones, with the façades in its own JVM:
the plugin puts them on the target's runtime class path, and the messages are still encoded (the app's code is the
same everywhere). Both the façades and their proxies being on that class path, the proxies need a package of their own:
set `njaFacade { clientPackage = "…" }` (the plugin checks it before the JVM target compiles).

**One process on Android.** ART and HotSpot can't share a *thread* (both keep their state in TLS and guard zones on the
stack), but they can share a *process*:
Expand Down Expand Up @@ -100,21 +105,27 @@ Kotlin binaries (`-force_load` of jdk-mobile's static libraries, `-export_dynami

The façade's public API, parsed from its sources with Kotlin PSI: `Int`,
`Long`, `Double`, `Float`, `Boolean`, `Byte`, `Short`, `String` (length-prefixed UTF-8: NUL included), `ByteArray`,
enums (verbatim, bodies included), data classes (verbatim), classes (proxies, `AutoCloseable`, released on `close()` or
when collected), open/abstract/sealed classes and interfaces (hierarchy mirrored, objects wrapped in their most specific
`IntArray`, `LongArray`, `FloatArray`, `DoubleArray`, enums (verbatim, bodies included), data classes (verbatim), sealed
value hierarchies (a sealed interface or class whose nested cases are all data classes or objects: verbatim, by value,
recursive ones included), classes (proxies, released on `close()` or when collected; an `AutoCloseable`'s `close()`
closes the JVM object, then releases it), default arguments (overloads: the JVM applies the defaults), open/abstract/sealed classes and interfaces (hierarchy mirrored, objects wrapped in their most specific
exported type), nested classes (`Outer_Inner`), companion objects, extension and top-level functions, nullable types,
`List`/`Set`/`Map` (nested), lambdas as parameters (callbacks, valid during the call, exceptions rethrown as themselves)
and as return values (JVM lambdas the app calls), `suspend` functions (cancellable both ways) and `Flow` (credit-based
backpressure).

Private and internal declarations stay the JVM's, as does a constructor that is private, internal, or takes what can't
cross; a function whose parameters or result can't cross is left out.

JVM exceptions arrive as `JvmException` (with the JVM class name, message and stack); exceptions an app callback throws
come back out of the call as themselves. A closed proxy fails with `IllegalStateException`; `close()` releases the JVM
object once the calls using it are done (receiver *and* arguments are leased).

## Tests

`examples/calculator` runs a suite of 1,977 tests (types, callbacks, suspend, flows, inheritance, load, concurrency,
monkey and torture tests) against a calculator façade, on iOS and on Android, from `commonTest`, plus NJA's own
`examples/calculator` runs a suite of 2,008 tests (types, arrays, sealed values, callbacks, suspend, flows, inheritance,
load, concurrency, monkey and torture tests) against a calculator façade, on iOS, on Android and on the JVM, from
`commonTest`, plus NJA's own
torture suite (`NjaTortureTest`): JVM null checks and stack overflows on 16 threads while the app faults and
collects, JIT deoptimization storms, 300-level JVM ↔ app nesting, callbacks invoked from the wrong JVM thread, thread
churn (1,000 threads, no JVM thread leak), 24–48 MB payloads, 100k handles released by close and by collection,
Expand All @@ -128,6 +139,10 @@ cancellation storms, 200k-element flows, a 20 s chaos soak on 24 threads.
./gradlew :examples:calculator:connectedAndroidDeviceTest
```

```bash
./gradlew :examples:calculator:jvmTest
```

## Performance

See [BENCHMARKS.md](BENCHMARKS.md). In short, on Android NJA's HotSpot runs Jackson and Commons Math 1.8–7.8× faster
Expand Down
2 changes: 2 additions & 0 deletions examples/calculator-facade/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ kotlin {

njaFacade {
libName = "calculator"
// Apart from the façade's: the JVM target has both on its class path
clientPackage = "com.example.calculator.client"
}

dependencies {
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
package com.example.calculator

/** A vector and its ids, primitive arrays inside a data class. */
data class Embedding(val ids: LongArray, val values: FloatArray, val label: String)

/** Primitive arrays crossing the bridge: as parameters, results, nullables, in data classes and in callbacks. */
class ArrayOps {
fun sumInts(values: IntArray): Long = values.fold(0L) { sum, v -> sum + v }

fun reverseLongs(values: LongArray): LongArray = values.reversedArray()

fun scale(values: FloatArray, factor: Float): FloatArray = FloatArray(values.size) { values[it] * factor }

fun squares(count: Int): DoubleArray = DoubleArray(count) { (it * it).toDouble() }

fun sizeOf(values: LongArray?): Int = values?.size ?: -1

fun maybe(present: Boolean): IntArray? = if (present) intArrayOf(1, 2, 3) else null

fun normalize(embedding: Embedding): Embedding {
val norm = kotlin.math.sqrt(embedding.values.fold(0.0) { s, v -> s + v * v }).toFloat()
return embedding.copy(values = FloatArray(embedding.values.size) { embedding.values[it] / norm }, label = embedding.label + "/n")
}

fun mapThroughApp(values: DoubleArray, transform: (DoubleArray) -> DoubleArray): DoubleArray = transform(values)

fun bits(): FloatArray = floatArrayOf(Float.NaN, Float.POSITIVE_INFINITY, Float.NEGATIVE_INFINITY, -0.0f, Float.MIN_VALUE, Float.MAX_VALUE)
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
package com.example.calculator

import java.util.concurrent.atomic.AtomicInteger

/** A JVM resource: closing its proxy closes it, once. */
class Resource(val name: String) : AutoCloseable {
@Volatile private var open = true

fun isOpen(): Boolean = open

override fun close() {
if (open) closes.incrementAndGet()
open = false
}

companion object {
private val closes = AtomicInteger()

fun closeCount(): Int = closes.get()
}
}

/** A class the app gets from a factory only: its constructor is internal, its state private. */
class Ticket internal constructor(private val secret: Long, val label: String) {
fun check(guess: Long): Boolean = guess == secret
}

class TicketOffice {
fun issue(label: String): Ticket = Ticket(label.length * 7L, label)
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
package com.example.calculator

/** A sealed value hierarchy: figures travel by value, nested in one another. */
sealed interface Figure {
data class Circle(val radius: Double) : Figure

data class Rect(val width: Double, val height: Double) : Figure

data class Group(val name: String, val children: List<Figure>, val anchor: Figure? = null) : Figure

data object Empty : Figure
}

/** A data class holding a sealed value: the recursion goes through it too. */
data class Layer(val shape: Figure, val tags: Set<String>)

/** A sealed class of values. */
sealed class Op {
data class Add(val a: Long, val b: Long) : Op()

data class Sum(val values: LongArray) : Op()

data object Noop : Op()
}

class Geometry {
fun area(shape: Figure): Double = when (shape) {
is Figure.Circle -> Math.PI * shape.radius * shape.radius
is Figure.Rect -> shape.width * shape.height
is Figure.Group -> shape.children.sumOf { area(it) }
Figure.Empty -> 0.0
}

fun scale(shape: Figure, factor: Double): Figure = when (shape) {
is Figure.Circle -> Figure.Circle(shape.radius * factor)
is Figure.Rect -> Figure.Rect(shape.width * factor, shape.height * factor)
is Figure.Group -> shape.copy(children = shape.children.map { scale(it, factor) }, anchor = shape.anchor?.let { scale(it, factor) })
Figure.Empty -> Figure.Empty
}

fun flatten(shape: Figure): List<Figure> = if (shape is Figure.Group) shape.children.flatMap { flatten(it) } else listOf(shape)

fun nested(depth: Int): Figure = if (depth == 0) Figure.Empty else Figure.Group("level $depth", listOf(nested(depth - 1), Figure.Circle(depth.toDouble())))

fun depth(shape: Figure): Int = if (shape is Figure.Group) 1 + (shape.children.maxOfOrNull { depth(it) } ?: 0) else 0

fun layerArea(layer: Layer): Double = area(layer.shape) * layer.tags.size

fun maybe(present: Boolean): Figure? = if (present) Figure.Rect(2.0, 3.0) else null

fun eval(op: Op): Long = when (op) {
is Op.Add -> op.a + op.b
is Op.Sum -> op.values.sum()
Op.Noop -> 0
}

fun viaApp(shape: Figure, transform: (Figure) -> Figure): Figure = transform(shape)

/** Default arguments: the app may leave out the trailing ones, the JVM fills them in. */
fun describe(shape: Figure, decimals: Int = 1, unit: String = "u²"): String = String.format(java.util.Locale.ROOT, "%.${decimals}f %s", area(shape), unit)
}
2 changes: 2 additions & 0 deletions examples/calculator/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ kotlin {
}
iosSimulatorArm64()
iosArm64()
// The desktop: the façades in this JVM, the same suites
jvm()

compilerOptions {
optIn.add("kotlin.concurrent.atomics.ExperimentalAtomicApi")
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

actual class Thread actual constructor(body: () -> Unit) {
// A JVM-like 8 MB stack, as the iOS threads (deep JVM <-> app nesting recurses on both sides)
Expand Down Expand Up @@ -30,6 +30,8 @@ internal actual fun platformGc() {

internal actual fun platformGetenv(name: String): String? = java.lang.System.getenv(name)

internal actual fun hostJvmVersion(): String? = null

private val missing: String? get() = java.lang.System.getProperty("nja.missing.property")

internal actual fun appFaultStorm(count: Int): Int {
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
package com.example.calculator.client

import kotlin.test.Test
import kotlin.test.assertContentEquals
import kotlin.test.assertEquals
import kotlin.test.assertNull

class ArraysTest {
private val ops = ArrayOps()

@Test
fun `primitive arrays go both ways`() {
assertEquals(6L, ops.sumInts(intArrayOf(1, 2, 3)))
assertEquals(0L, ops.sumInts(IntArray(0)))
assertContentEquals(longArrayOf(Long.MAX_VALUE, 0, Long.MIN_VALUE), ops.reverseLongs(longArrayOf(Long.MIN_VALUE, 0, Long.MAX_VALUE)))
assertContentEquals(floatArrayOf(2f, -4f), ops.scale(floatArrayOf(1f, -2f), 2f))
assertContentEquals(doubleArrayOf(0.0, 1.0, 4.0, 9.0), ops.squares(4))
}

@Test
fun `large arrays`() {
val ids = LongArray(200_000) { it * 3L }
assertContentEquals(ids.reversedArray(), ops.reverseLongs(ids))
assertEquals(200_000, ops.squares(200_000).size)
}

@Test
fun `nullable arrays`() {
assertEquals(-1, ops.sizeOf(null))
assertEquals(2, ops.sizeOf(longArrayOf(1, 2)))
assertNull(ops.maybe(false))
assertContentEquals(intArrayOf(1, 2, 3), ops.maybe(true))
}

@Test
fun `arrays in a data class`() {
val normalized = ops.normalize(Embedding(longArrayOf(7, 8), floatArrayOf(3f, 4f), "v"))
assertContentEquals(longArrayOf(7, 8), normalized.ids)
assertContentEquals(floatArrayOf(0.6f, 0.8f), normalized.values)
assertEquals("v/n", normalized.label)
}

@Test
fun `arrays through a callback`() {
assertContentEquals(doubleArrayOf(2.0, 4.0), ops.mapThroughApp(doubleArrayOf(1.0, 2.0)) { a -> DoubleArray(a.size) { a[it] * 2 } })
}

@Test
fun `float bits survive`() {
val bits = ops.bits()
assertEquals(6, bits.size)
assert(bits[0].isNaN()) { "NaN" }
assertEquals(Float.POSITIVE_INFINITY, bits[1])
assertEquals(Float.NEGATIVE_INFINITY, bits[2])
assertEquals((-0.0f).toRawBits(), bits[3].toRawBits())
assertEquals(Float.MIN_VALUE, bits[4])
assertEquals(Float.MAX_VALUE, bits[5])
}
}
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import kotlin.test.Test
import kotlin.test.assertEquals
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import kotlin.test.Test
import kotlin.test.assertEquals
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import kotlin.test.Test
import kotlin.test.assertEquals
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import kotlin.test.Test
import kotlin.test.assertEquals
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import kotlin.test.Test
import kotlin.test.assertEquals
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import kotlin.test.Test
import kotlin.test.assertEquals
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import kotlinx.coroutines.runBlocking
import kotlin.random.Random
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import kotlin.test.Test
import kotlin.test.assertEquals
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import dev.nucleusframework.nja.JvmException

Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import kotlin.test.Test
import kotlin.test.assertEquals
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import kotlin.test.Test
import kotlin.test.assertEquals
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import dev.nucleusframework.nja.JvmException

Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import kotlin.test.Test
import kotlin.test.assertEquals
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import dev.nucleusframework.nja.JvmException

Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import kotlin.test.Test
import kotlin.test.assertEquals
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import dev.nucleusframework.nja.JvmException

Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import kotlin.test.Test
import kotlin.test.assertEquals
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import kotlin.test.Test
import kotlin.test.assertEquals
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package com.example.calculator
package com.example.calculator.client

import kotlin.test.Test
import kotlin.test.assertEquals
Expand Down
Loading