ImportedApiSAB.java

package client.teavm;

import client.teavm.common.IImportedApi;
import client.teavm.common.parameter.event.IImportEventParameters;
import libsidplay.components.printer.IPaper.Outputs;
import org.teavm.jso.JSObject;
import org.teavm.jso.browser.Window;
import org.teavm.jso.core.*;
import org.teavm.jso.typedarrays.*;

import java.nio.ByteBuffer;

import static java.nio.ByteOrder.BIG_ENDIAN;
import static java.nio.ByteOrder.LITTLE_ENDIAN;

/**
 * SharedArrayBuffer (SAB)-based implementation of {@link client.teavm.ImportedApi}.
 *
 * <p>
 * This class enables high-performance, zero-copy data exchange between a TeaVM Web Worker and the browser main thread.
 * Large buffers for audio, video, and oscilloscope data are shared via {@link java.nio.ByteBuffer} backed by SABs, and
 * synchronization is achieved using atomic operations on a small control buffer.
 * </p>
 *
 * <h2>Buffers</h2>
 * <ul>
 * <li><b>Audio samples:</b> Written by the worker and read by the main
 * thread.</li>
 * <li><b>Video frame:</b> Written by the worker and read by the main
 * thread.</li>
 * <li><b>Oscilloscope batches:</b> Three shared slots carry packed SID/OPL snapshots.</li>
 * </ul>
 *
 * <h2>Control Buffer</h2>
 * <p>
 * A small {@code Int32Array} stores atomic flags for synchronization:
 * </p>
 *
 * <pre>
 * jsControlBuffer[0] → SAMPLE_FLAG_INDEX (audio ready)
 * jsControlBuffer[1+] → FRAME0_FLAG_INDEX + bufferIndex (video ready per buffer, double buffer)
 * jsControlBuffer[3] → WHATSSID_FLAG_INDEX (WAV ready)
 * jsControlBuffer[4..6] → three nonblocking snapshot batch slots
 * </pre>
 *
 * <p>
 * Flag values:
 * </p>
 * <ul>
 * <li>{@link Control.Flags#READY}</li>
 * <li>{@link Control.Flags#NOT_READY}</li>
 * </ul>
 *
 * <h2>Synchronization Protocol</h2>
 * <ol>
 * <li>Worker writes to a buffer and sets the corresponding flag to
 * {@link Control.Flags#READY}.</li>
 * <li>Main thread processes the buffer, resets the flag to
 * {@link Control.Flags#NOT_READY}, and notifies the
 * worker.</li>
 * <li>Audio/video workers wait using {@link org.teavm.jso.typedarrays.Atomics#wait}
 * until the flag is cleared. Oscilloscope publication instead reserves a free
 * slot atomically. Snapshot batches retain pending frames in their bounded
 * producer queue when all three transport slots are occupied.</li>
 * </ol>
 *
 * <p>
 * This approach ensures efficient handshaking for real-time audio/video data
 * without copying large arrays. Oscilloscope consumers copy their snapshot
 * before releasing a slot, so delayed rendering cannot block synthesis.
 * </p>
 * Frames use a double-buffer technique to ensure efficient handshaking for real-time video.
 * While the second buffer is produced, the first buffer can still be consumed.
 * </p>
 */
public final class ImportedApiSAB implements IImportedApi, IImportEventParameters {

    private static final String EVENT_TYPE = "eventType";
    private static final String EVENT_DATA = "eventData";

    private static final int WAIT_TIMEOUT = 30;

    /**
     * Control buffer contents: One Integer per buffer: sampleBuffer + 2 * frameBuffer (double buffer) + whatssidBuffer
     * + 3 batch slots
     */
    public static final class Control {
        private static final int BUFFER_LEN = 1 + 2 + 1 + 3;

        // A JS view does not retain TeaVM's direct allocation. Keep its Java owner
        // alive while either thread can access the synchronization flags.
        private static ByteBuffer controlBuffer;
        private static Int32Array jsControlBuffer;

        public static final int SAMPLE_FLAG_INDEX = 0;
        public static final int FRAME0_FLAG_INDEX = 1; /* , 2 */
        public static final int WHATSSID_FLAG_INDEX = 3;
        public static final int BATCH_FLAG_INDEX = 4;  /* , 5, 6 */

        public static final class Flags {
            public static final int NOT_READY = 0;
            public static final int READY = 1;
            public static final int WRITING = 2;
        }
    }

    @Override
    public boolean supportsWarp() {
        return true;
    }

    @Override
    public void processWarp(boolean enabled) {
        ImportedApi.processWarpJS(enabled);
    }

    @Override
    public void processInspection(String json) {
        ImportedApi.processInspectionJS(json);
    }

    @Override
    public void initControlBuffer() {
        Control.controlBuffer = ByteBuffer.allocateDirect(Control.BUFFER_LEN * Integer.BYTES).order(LITTLE_ENDIAN);

        // Initialize all flags to NOT_READY
        for (int i = 0; i < Control.BUFFER_LEN; i++) {
            Control.controlBuffer.putInt(i * Integer.BYTES, Control.Flags.NOT_READY);
        }

        // Inform the main thread about the control buffer
        JSMapLike<JSObject> message = JSObjects.create();
        message.set(EVENT_TYPE, JSString.valueOf(EVENT_INIT_CONTROL_BUFFER_SAB));
        JSMapLike<JSObject> eventData = JSObjects.create();
        eventData.set(CONTROL_BUFFER, Control.jsControlBuffer = Int32Array.fromJavaBuffer(Control.controlBuffer));
        message.set(EVENT_DATA, eventData);

        Window.worker().postMessage(message);
    }

    @Override
    public ByteBuffer initSampleBuffer(int chunkFrames, int channels) {
        // Create a shared buffer for audio samples
        ByteBuffer samples = ByteBuffer.allocateDirect(chunkFrames * Short.BYTES * channels).order(LITTLE_ENDIAN);

        // Inform the main thread about the shared sample buffer
        JSMapLike<JSObject> message = JSObjects.create();
        message.set(EVENT_TYPE, JSString.valueOf(EVENT_INIT_SAMPLE_BUFFER_SAB));
        JSMapLike<JSObject> eventData = JSObjects.create();
        eventData.set(SAMPLE_BUFFER, Int8Array.fromJavaBuffer(samples));
        message.set(EVENT_DATA, eventData);

        Window.worker().postMessage(message);
        return samples;
    }

    @Override
    public ByteBuffer initFrameBuffer(int maxWidth, int maxHeight) {
        // Create a shared buffer for video frame (RGBA, big-endian order) and twice (double-buffer technique)
        ByteBuffer pixels = ByteBuffer.allocateDirect(2 * maxWidth * maxHeight << 2).order(BIG_ENDIAN);

        // Inform the main thread about the shared pixel buffer
        JSMapLike<JSObject> message = JSObjects.create();
        message.set(EVENT_TYPE, JSString.valueOf(EVENT_INIT_FRAME_BUFFER_SAB));
        JSMapLike<JSObject> eventData = JSObjects.create();
        eventData.set(FRAME_BUFFER, Uint8Array.fromJavaBuffer(pixels));
        message.set(EVENT_DATA, eventData);

        Window.worker().postMessage(message);
        return pixels;
    }

    @Override
    public ByteBuffer initWhatsSidBuffer(int wavLength) {
        // Create a shared buffer for WhatsSid wav output
        ByteBuffer whatsSidBuffer = ByteBuffer.allocateDirect(wavLength).order(LITTLE_ENDIAN);

        // Inform the main thread about WAV buffer
        JSMapLike<JSObject> message = JSObjects.create();
        message.set(EVENT_TYPE, JSString.valueOf(EVENT_INIT_WHATSSID_SAB));
        JSMapLike<JSObject> eventData = JSObjects.create();
        eventData.set(WHATSSID_BUFFER, Int8Array.fromJavaBuffer(whatsSidBuffer));
        message.set(EVENT_DATA, eventData);

        Window.worker().postMessage(message);
        return whatsSidBuffer;
    }

    @Override
    public ByteBuffer initOscBatchBuffer(int length, int slot) {
        // Create a shared buffer for oscilloscope output per slot
        ByteBuffer oscBatchBuffer = ByteBuffer.allocateDirect(length).order(LITTLE_ENDIAN);

        // Inform the main thread about oscilloscope buffer
        JSMapLike<JSObject> message = JSObjects.create();
        message.set(EVENT_TYPE, JSString.valueOf(EVENT_INIT_OSC_BATCH_BUFFER_SAB));
        JSMapLike<JSObject> eventData = JSObjects.create();
        eventData.set(BUFFER_INDEX, JSNumber.valueOf(slot));
        eventData.set(OSC_BUFFER, Int8Array.fromJavaBuffer(oscBatchBuffer));
        message.set(EVENT_DATA, eventData);

        Window.worker().postMessage(message);
        return oscBatchBuffer;
    }

    @Override
    public void processSamples(long absTime, ByteBuffer sampleBuffer, float[] lookupTable) {
        // --- Notify the main thread that new audio data is ready ---
        Atomics.store(Control.jsControlBuffer, Control.SAMPLE_FLAG_INDEX, Control.Flags.READY);

        JSMapLike<JSObject> message = JSObjects.create();
        message.set(EVENT_TYPE, JSString.valueOf(EVENT_SAMPLES_SAB));
        JSMapLike<JSObject> eventData = JSObjects.create();
        eventData.set(ABS_TIME, JSBigInt.valueOf(absTime));
        message.set(EVENT_DATA, eventData);
        Window.worker().postMessage(message);

        // --- Wait until the main thread acknowledges consumption ---
        while (Atomics.load(Control.jsControlBuffer, Control.SAMPLE_FLAG_INDEX) == Control.Flags.READY) {
            // wait until no longer READY
            Atomics.wait(Control.jsControlBuffer, Control.SAMPLE_FLAG_INDEX, Control.Flags.READY, WAIT_TIMEOUT);
        }
    }

    private int currentBuffer = 0;

    @Override
    public void prepareFrame(ByteBuffer pixels) {
        // Choose frame 1 or frame 2 start position
        pixels.position(currentBuffer > 0 ? pixels.capacity() >> 1 : 0);
    }

    @Override
    public void processFrame(long absTime, ByteBuffer pixels) {
        int completedBuffer = currentBuffer;

        // --- Notify the main thread that new frame data is ready ---
        Atomics.store(Control.jsControlBuffer, Control.FRAME0_FLAG_INDEX << completedBuffer, Control.Flags.READY);

        JSMapLike<JSObject> message = JSObjects.create();
        message.set(EVENT_TYPE, JSString.valueOf(EVENT_FRAME_SAB));
        JSMapLike<JSObject> eventData = JSObjects.create();
        eventData.set(ABS_TIME, JSBigInt.valueOf(absTime));
        eventData.set(BUFFER_INDEX, JSNumber.valueOf(completedBuffer));
        message.set(EVENT_DATA, eventData);
        Window.worker().postMessage(message);

        // Acquire the other buffer for the next rendering operation.
        int nextBuffer = 1 - currentBuffer;
        currentBuffer = nextBuffer;

        // --- Wait until the main thread acknowledges consumption ---
        while (Atomics.load(Control.jsControlBuffer, Control.FRAME0_FLAG_INDEX + nextBuffer) == Control.Flags.READY) {
            // wait until no longer READY
            Atomics.wait(Control.jsControlBuffer, Control.FRAME0_FLAG_INDEX + nextBuffer, Control.Flags.READY, WAIT_TIMEOUT);
        }
    }

    @Override
    public void whatsSid(ByteBuffer whatsSidBuffer) {
        // --- Notify the main thread that new frame data is ready ---
        Atomics.store(Control.jsControlBuffer, Control.WHATSSID_FLAG_INDEX, Control.Flags.READY);

        JSMapLike<JSObject> message = JSObjects.create();
        message.set(EVENT_TYPE, JSString.valueOf(EVENT_WHATSSID_SAB));
        JSMapLike<JSObject> eventData = JSObjects.create();
        message.set(EVENT_DATA, eventData);
        Window.worker().postMessage(message);

        // --- Wait until the main thread acknowledges consumption ---
        while (Atomics.load(Control.jsControlBuffer, Control.WHATSSID_FLAG_INDEX) == Control.Flags.READY) {
            // wait until no longer READY
            Atomics.wait(Control.jsControlBuffer, Control.WHATSSID_FLAG_INDEX, Control.Flags.READY, WAIT_TIMEOUT);
        }
    }

    @Override
    public int prepareOscBatch() {
        // Skip a busy slot so a delayed browser cannot stall synthesis (non-blocking).
        for (int slot = 0; slot < 3; slot++) {
            // Acquire exclusive ownership (NOT_READY -> WRITING transition)
            if (Atomics.compareExchange(Control.jsControlBuffer, Control.BATCH_FLAG_INDEX + slot,
                    Control.Flags.NOT_READY, Control.Flags.WRITING) == Control.Flags.NOT_READY) {
                // slot acquired
                return slot;
            }
        }
        // all three slots are busy
        return -1;
    }

    @Override
    public void processOscBatch(ByteBuffer frame, int slot) {
        Atomics.store(Control.jsControlBuffer, Control.BATCH_FLAG_INDEX + slot, Control.Flags.READY);

        JSMapLike<JSObject> message = JSObjects.create();
        message.set(EVENT_TYPE, JSString.valueOf(EVENT_OSC_BATCH_SAB));
        JSMapLike<JSObject> eventData = JSObjects.create();
        eventData.set(BUFFER_INDEX, JSNumber.valueOf(slot));
        eventData.set(LENGTH, JSNumber.valueOf(frame.limit()));
        message.set(EVENT_DATA, eventData);

        Window.worker().postMessage(message);
    }

    @Override
    public void processAudioTiming(ByteBuffer timing) {
        ImportedApi.processAudioTimingJS(timing.array(), timing.limit());
    }

    @Override
    public void processOscSources(int type, int generation) {
        JSMapLike<JSObject> message = JSObjects.create();
        message.set(EVENT_TYPE, JSString.valueOf(EVENT_OSC_SOURCES));
        JSMapLike<JSObject> eventData = JSObjects.create();
        eventData.set(OPL_TYPE, JSNumber.valueOf(type));
        eventData.set(GENERATON, JSNumber.valueOf(generation));
        message.set(EVENT_DATA, eventData);

        Window.worker().postMessage(message);
    }

    @Override
    public void processSidWrite(int sidNum, long absTime, int relTime, int addr, int value) {
        ImportedApi.processSidWriteJS(sidNum, absTime, relTime, addr, value);
    }

    @Override
    public void processTimerEnd(double end) {
        JSMapLike<JSObject> message = JSObjects.create();
        message.set(EVENT_TYPE, JSString.valueOf(EVENT_TIMER_END));
        JSMapLike<JSObject> eventData = JSObjects.create();
        eventData.set(END, JSNumber.valueOf(end));
        message.set(EVENT_DATA, eventData);
        Window.worker().postMessage(message);
    }

    @Override
    public void processPrinter(Outputs output) {
        JSMapLike<JSObject> message = JSObjects.create();
        message.set(EVENT_TYPE, JSString.valueOf(EVENT_PRINTER));
        JSMapLike<JSObject> eventData = JSObjects.create();
        eventData.set(OUTPUT, JSString.valueOf(output.name()));
        message.set(EVENT_DATA, eventData);
        Window.worker().postMessage(message);
    }

    @Override
    public void processGeoRAMImage(byte[] contents) {
        ImportedApi.processGeoRAMImageJS(contents, contents.length);
    }

}