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);
}
}