Reduce main thread dispatch if not needed

[MaxHeimbrock]

Move latency-sensitive FFI events off the main thread

Summary

Internal threading change. FFI events whose handlers don't touch Unity APIs now run directly on the FFI callback thread instead of being marshaled to Unity's main thread via SynchronizationContext.Post. Saves up to one frame of latency on async ops, log delivery, and stream chunk arrival, and removes a small but real allocation per event from the main-thread queue.

No public API changes. The user-facing threading contract is unchanged: Room.ParticipantConnected, TrackPublished, VideoStream.TextureReceived, RPC handlers, Disconnect, etc. all still fire on the main thread.

Why

FFICallback previously routed every Rust event (except AudioStreamEvent) through _context.Post to Unity's main thread. That's the safe default for handlers that touch Unity APIs (Texture2D, GameObject, Transform, …) but it costs one frame of latency for handlers that don't. Three categories of events are silently paying that cost without benefit:

1. One-shot async completions that only flip IsDone on a YieldInstruction — SetMetadata, UnpublishTrack, all stream Read/Write/Close ops.
2. Stream reader chunk events that just append bytes/strings to an internal buffer.
3. Log batches — UnityEngine.Debug.unityLogger is documented thread-safe; the post hop adds latency without benefit, especially during error storms or LK_VERBOSE noise.

This PR moves only those off the main thread. Bespoke completion handlers (anything that fires user events or constructs Unity objects) keep main-thread dispatch.

Event dispatch matrix

After this PR:

Event	Where it runs	Why
AudioStreamEvent	FFI thread (unchanged)	Audio thread consumes the data; main-thread latency would hurt timing
Logs	FFI thread (new)	Debug.unityLogger is thread-safe; logs reach console immediately during panics / errors
ByteStreamReaderEvent	FFI thread (new)	Internal buffer is now lock-protected; chunks land without frame delay
TextStreamReaderEvent	FFI thread (new)	Same lock as byte path (shared ReadIncrementalInstructionBase)
One-shot completions via FfiInstruction<T>	FFI thread (new)	SetLocalMetadata, SetLocalName, SetLocalAttributes, UnpublishTrack — only flip IsDone/IsError
One-shot completions via FfiStreamInstruction<T>	FFI thread (new)	ByteStreamWriter.Write/Close, TextStreamWriter.Write/Close
One-shot completions via FfiStreamResultInstruction<T,U>	FFI thread (new)	ByteStreamReader.ReadAll/WriteToFile, TextStreamReader.ReadAll
RoomEvent	Main thread	Fires user-facing ParticipantConnected, TrackPublished, etc.
TrackEvent	Main thread	(No subscribers today; main-thread default for safety)
RpcMethodInvocation	Main thread	User RPC handlers commonly touch game state
Disconnect	Main thread	UI updates typical
VideoStreamEvent	Main thread	Internal buffering is fast; user-facing raw delivery deferred (see follow-ups)
DataTrackStreamEvent	Main thread	Deferred until a concrete consumer asks
Connect (one-shot)	Main thread	Bespoke handler fires participant-connected events
PublishTrack (one-shot)	Main thread	Bespoke handler
GetStats (one-shot)	Main thread	Bespoke handler
CaptureAudioFrame (one-shot)	Main thread	Bespoke handler
PerformRpc (one-shot)	Main thread	Bespoke handler surfaces response
SendText / SendFile (one-shot)	Main thread	Bespoke handlers
TextStreamOpen / ByteStreamOpen (one-shot)	Main thread	Bespoke handlers return writer objects
PublishDataTrack (one-shot)	Main thread	Bespoke handler

Decision logic at runtime

FFICallback now only parses bytes and delegates to RouteFfiEvent. The routing decision lives in one place (Runtime/Scripts/Internal/FFIClient.cs):

internal static void RouteFfiEvent(FfiEvent response)
{
    if (_isDisposed) return;

    // 1. Per-event-type fast paths — invoke handler directly on FFI thread.
    if (response.MessageCase == FfiEvent.MessageOneofCase.AudioStreamEvent)      { ...; return; }
    if (response.MessageCase == FfiEvent.MessageOneofCase.Logs)                  { ...; return; }
    if (response.MessageCase == FfiEvent.MessageOneofCase.ByteStreamReaderEvent) { ...; return; }
    if (response.MessageCase == FfiEvent.MessageOneofCase.TextStreamReaderEvent) { ...; return; }

    // 2. One-shot completion fast path — opted-in pending callbacks complete inline.
    var requestAsyncId = ExtractRequestAsyncId(response);
    if (requestAsyncId.HasValue && Instance.TrySkipDispatch(requestAsyncId.Value, response))
        return;

    // 3. Fallback — post to Unity's main-thread sync context.
    Instance._context?.Post(static (resp) =>
    {
        var r = resp as FfiEvent;
        if (r == null) return;
        DispatchEvent(r);
    }, response);
}

TrySkipDispatch looks up the registered pending callback and only handles the event inline if the callback opted out of main-thread dispatch:

internal bool TrySkipDispatch(ulong requestAsyncId, FfiEvent ffiEvent)
{
    if (!pendingCallbacks.TryGetValue(requestAsyncId, out var pending)) return false;
    if (pending.DispatchToMainThread) return false;
    return TryDispatchPendingCallback(requestAsyncId, ffiEvent);
}

Three exit points:

1. No matching pending entry → false. (Either not a one-shot completion, or already cancelled.)
2. Entry exists with DispatchToMainThread == true → false. Caller falls through to _context.Post.
3. Entry exists with DispatchToMainThread == false → run completion inline, return true.

Opt-in flow at registration

The default is conservative — every RegisterPendingCallback callsite implicitly requires main-thread dispatch:

internal void RegisterPendingCallback<TCallback>(
    ulong requestAsyncId,
    Func<FfiEvent, TCallback?> selector,
    Action<TCallback> onComplete,
    Action? onCancel = null,
    bool dispatchToMainThread = true   // safe default
) where TCallback : class

The three generic FfiInstruction* classes opt out, because their onComplete only mutates volatile YieldInstruction state:

// FfiInstruction.cs
FfiClient.Instance.RegisterPendingCallback(
    asyncId,
    selector,
    onComplete,
    onCancel,
    dispatchToMainThread: false);

The ten bespoke registration sites (Connect, PublishTrack, GetStats, …) keep the default. They fire user events, construct C# objects, or otherwise touch Unity-visible state.

To make YieldInstruction safe to read across threads, IsDone and IsError (and the corresponding IsEos/IsCurrentReadDone on StreamYieldInstruction) are backed by volatile fields. The release semantics of the IsDone write make any preceding state mutations (Error, _result, …) visible to the main-thread reader after it observes IsDone == true.

Tests

Eleven new EditMode tests, all bounded with explicit DateTime.UtcNow deadlines and Thread.Join(TimeSpan)/ManualResetEventSlim.Wait(TimeSpan) so a deadlock or volatile regression fails fast with a descriptive Assert.Fail rather than hanging the runner.

Test file	Tests	What it guards
Tests/EditMode/YieldInstructionThreadingTests.cs	3	Cross-thread visibility of volatile IsDone/IsError; keepWaiting flips after a background completion
Tests/EditMode/DataStreamIncrementalReadTests.cs (extended)	+3	Concurrent producer/consumer over 5000 chunks; OnEos racing with chunks; Reset racing with OnChunk (200 trials)
Tests/EditMode/SkipDispatchTests.cs	5	Inline dispatch lands on the dispatching thread; main-thread entries reach SynchronizationContext.Post; integration via RouteFfiEvent

The RouteFfiEvent integration tests are the load-bearing ones. They drive the same code path FFICallback uses, so a future refactor that drops the TrySkipDispatch short-circuit fails them with a clear message:

Completion did not run — RouteFfiEvent may be missing the TrySkipDispatch call for inline entries.

Verified by negative control: temporarily commenting out the TrySkipDispatch call in RouteFfiEvent reproduced exactly that failure on the first run.

The non-raw integration test (RouteFfiEvent_MainThreadCallback_PostsToSynchronizationContext_AndDrainsCompletion) installs a RecordingSynchronizationContext as FfiClient._context for the test duration, calls RouteFfiEvent from a background thread, and asserts: (a) the completion did not run on the dispatcher thread, (b) exactly one item was posted, (c) draining the queue from the test thread runs the completion on the drainer thread.