Compose effect APIs: LaunchedEffect / DisposableEffect / SideEffect

[jonathanpeppers]

Closes #57. Implements phase 4 of #66 (#102).

What

Bind Compose's three side-effect entry points onto the C# facade — with both static call shape (consistent with Compose.Remember / Compose.RememberSaveable) and node call shape (drop-in inside collection-initializer trees):

// Static shape — call from inside any composition body
Compose.SideEffect(() => Log.Info("rendered"));
Compose.DisposableEffect(_sensorId, scope =>
{
    var registration = SensorRegistry.Subscribe(_sensorId, OnTick);
    return () => registration.Dispose();
});
Compose.LaunchedEffect("once", async ct =>
{
    while (!ct.IsCancellationRequested)
    {
        await Task.Delay(1000, ct);
        _ticks.Value++;
    }
});

// Node shape — inside any container's collection-initializer
new Column
{
    new Text(_count.ToString()),
    new SideEffect(() => _logger.Trace("recomposed")),
    new LaunchedEffect(_sessionId, async ct => await SyncAsync(ct)),
    new DisposableEffect(_sensorId, scope => /* ... */),
}

Each effect has 1/2/3-key overloads (matching Kotlin's LaunchedEffect(key1) / LaunchedEffect(key1, key2) / LaunchedEffect(key1, key2, key3)). Keys can be any Java peer, string, char, bool, or .NET primitive — boxed once per call via BoxKey.

Why no [ComposeBridge]

Xamarin.AndroidX.Compose.Runtime.Android 1.11.2.1 fully binds EffectsKt.SideEffect / LaunchedEffect / DisposableEffect (their Kotlin signatures don't carry @JvmInline value class parameters, so they don't trip dotnet/java-interop#1440). The only raw JNI in this PR is for kotlin.ResultKt.createFailure(Throwable) — a value class member the binder still strips — used to surface C# Task faults as Kotlin Result.Failure boxes.

How LaunchedEffect bridges C# Task ↔ Kotlin suspend

The shape Kotlin's LaunchedEffect expects is suspend (CoroutineScope) -> Unit, which the binder surfaces as IFunction2<CoroutineScope, Continuation<Unit>, Object?> plus the COROUTINE_SUSPENDED sentinel protocol.

LaunchedEffectBody.Invoke:

1. Allocates a CancellationTokenSource for this invocation.
2. Pulls the IJob out of continuation.Context and registers a JobCompletionHandler via InvokeOnCompletion(onCancelling: true, invokeImmediately: true, …). The 3-arg overload is required — the 1-arg form only fires after full completion, which is too late to cancel a still-suspended C# Task.Delay.
3. Calls the user's Func<CancellationToken, Task>.
4. Hooks a Task.ContinueWith that resumes the Kotlin continuation:
   • Faulted Task → Result.Failure(toThrowable(ex)) (full ex.ToString() preserved in the message).
   • Cancelled Task → Result.Failure(java.util.concurrent.CancellationException) (kotlinx.coroutines.CancellationException is a typealias for the j.u.c. one on JVM).
   • Successful Task → Kotlin.Unit.Instance.
   • An Interlocked.CompareExchange once-gate keeps a racing job-cancellation handler firing and a late Task completion from double-resuming the continuation.
5. Returns IntrinsicsKt.COROUTINE_SUSPENDED so Kotlin awaits the deferred resume.

A synchronous fault from body(ct) (rare — async lambdas typically wrap their work in async) is rethrown as a Java.Lang.RuntimeException that includes ex.ToString(), so coroutine machinery records the failure on the Job and InvokeOnCompletion still fires.

What's not included

• rememberCoroutineScope — deferred. The common "kick off async work on click" pattern is covered by LaunchedEffect("once", body) plus a key bump from the button's onClick. Filing as a follow-up issue.
• vararg-key overloads — the 1/2/3-key overloads cover the common case without per-render Object[] allocation. BoxKeyArray is wired up internally for when we add the public variadic overload.

Sample

MainActivity.cs gains an "⚡ Effects" tab. Ticking counter is incremented by a LaunchedEffect, "Restart effects" bumps the key (cancels the previous Task, fires the previous DisposableEffect's cleanup, re-runs both with the new key), and SideEffect writes a line to logcat (adb logcat -s ComposeNet.Sample:D) on every recomposition of the tab.

Validation

• dotnet build src/ComposeNet.Compose — clean.
• dotnet build src/ComposeNet.Sample — clean.
• dotnet test src/ComposeNet.SourceGenerators.Tests — 90/90 pass (the source generators don't touch effects).

Rubber-duck pass

• Resume-once race: gated by Interlocked.CompareExchange, with JobCompletionHandler firing → CTS.Cancel → user code observes ct → ContinueWith → resume. Synchronous-completion path goes through the same ContinueWith so there's a single resume entry point.
• JCW lifetime: LaunchedEffectBody / DisposableEffectBody / JobCompletionHandler are kept alive by Compose's slot table (Function2/Function1) and the Job's internal handler list (Function1). ResumeContext is held alive by TPL through the state arg of ContinueWith.
• BoxKey rejects unsupported types with NotSupportedException rather than silently identity-hashing them — boxed value types like Guid / DateTime / records would otherwise change identity per-render and infinitely restart the effect.

[Copilot]

Pull request overview

This PR implements Compose's three side-effect entry points (SideEffect, DisposableEffect, LaunchedEffect) as both static methods on Compose and tree-syntax ComposableNode wrappers, closing #57 and delivering Phase 4 of #66 (#102). Since Xamarin.AndroidX.Compose.Runtime.Android fully binds EffectsKt, the only raw JNI needed is for kotlin.ResultKt.createFailure (stripped due to @JvmInline value class mangling). The LaunchedEffect bridge is the most complex piece — it maps a C# Func<CancellationToken, Task> onto Kotlin's suspend (CoroutineScope) -> Unit coroutine protocol, with an Interlocked.CompareExchange gate preventing double-resume races and a JobCompletionHandler JCW wiring Kotlin Job cancellation into the managed CancellationTokenSource.

Changes:

• Adds static Compose.SideEffect, Compose.DisposableEffect (1/2/3-key), and Compose.LaunchedEffect (1/2/3-key) entry points plus matching ComposableNode wrappers for collection-initializer tree syntax.
• Introduces LaunchedEffectBody, DisposableEffectBody, JobCompletionHandler JCWs and EffectsBridges.cs (KotlinResultFailure, BoxKey) to bridge the coroutine/suspend protocol and box effect keys for Java equals comparison.
• Adds an "Effects" tab to the sample app demonstrating all three APIs with a ticking counter, disposal counter, and logcat output.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/ComposeNet.Compose/Compose.cs	Adds SideEffect, DisposableEffect (×3), LaunchedEffect (×3) static entry points using ComposeContext.Current and bound EffectsKt APIs.
src/ComposeNet.Compose/EffectsBridges.cs	Partial ComposeBridges extension with KotlinResultFailure (raw JNI), BoxKey/BoxKeyArray (key boxing), and unused KotlinUnit property.
src/ComposeNet.Compose/LaunchedEffectBody.cs	JCW implementing IFunction2 for the suspend lambda; bridges C# Task ↔ Kotlin continuation with ResumeOnceGate and ResumeContext.
src/ComposeNet.Compose/JobCompletionHandler.cs	JCW implementing IFunction1 registered on the coroutine Job to cancel the C# CancellationTokenSource.
src/ComposeNet.Compose/DisposableEffectBody.cs	JCW implementing IFunction1 for the disposable-effect body; wraps the onDispose Action in ComposableLambda0.
src/ComposeNet.Compose/SideEffect.cs	Tree-syntax ComposableNode wrapper delegating to Compose.SideEffect.
src/ComposeNet.Compose/LaunchedEffect.cs	Tree-syntax ComposableNode wrapper with 1/2/3-key constructor overloads.
src/ComposeNet.Compose/DisposableEffect.cs	Tree-syntax ComposableNode wrapper with 1/2/3-key constructor overloads.
src/ComposeNet.Compose/PublicAPI.Unshipped.txt	Registers all new public types, constructors, and static methods.
src/ComposeNet.Sample/MainActivity.cs	Adds "Effects" tab demonstrating LaunchedEffect tick loop, DisposableEffect cleanup counter, and SideEffect logcat output.