qwasmsuspendresumecontrol.cpp

Go to the documentation of this file.

// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
// Qt-Security score:significant reason:default
 
#include "qwasmsuspendresumecontrol_p.h"
#include "qstdweb_p.h"
 
#include <QtCore/qapplicationstatic.h>
#include <QtCore/qdebug.h>
 
#include <emscripten.h>
#include <emscripten/val.h>
#include <emscripten/bind.h>
 
using emscripten::val;
 
/*
    QWasmSuspendResumeControl controls asyncify suspend and resume when handling native events.
 
    The class supports registering C++ event handlers, and creates a corresponding
    JavaScript event handler which can be passed to addEventListener() or similar
    API:
 
      auto handler = [](emscripten::val argument){
         // handle event
      };
      uint32_t index = control->registerEventHandler(handler);
      element.call<void>("addEventListener", "eventname", control->jsEventHandlerAt(index));
 
    The wasm instance suspends itself by calling the suspend() function, which resumes
    and returns whenever there was a native event. Call sendPendingEvents() to send
    the native event and invoke the C++ event handlers.
 
      // about to suspend
      control->suspend(); // <- instance/app sleeps here
      // was resumed, send event(s)
      control->sendPendingEvents();
 
    QWasmSuspendResumeControl also supports the case where the wasm instance returns
    control to the browser's event loop (without suspending), and will call the C++
    event handlers directly in that case.
*/
 
Q_GLOBAL_STATIC(QWasmSuspendResumeControl, s_suspendResumeControl);
 
// Setup/constructor function for Module.suspendResumeControl.
// FIXME if assigning to the Module object from C++ is/becomes possible
// then this does not need to be a separate JS function.
void qtSuspendResumeControlClearJs() {
    EM_ASM({
        Module.qtSuspendResumeControl = ({
            resume: null,
            asyncifyEnabled: false, // asyncify 1 or JSPI enabled
            eventHandlers: {},
            pendingEvents: [],
            exclusiveEventHandler: 0,
        });
    });
}
 
// Suspends the calling thread
EM_ASYNC_JS(void, qtSuspendJs, (), {
    return new Promise(resolve => {
        Module.qtSuspendResumeControl.resume = resolve;
    });
});
 
// Registers a JS event handler which when called registers its index
// as the "current" event handler, and then resumes the wasm instance.
// The wasm instance will then call the C++ event after it is resumed.
void qtRegisterEventHandlerJs(int index) {
    EM_ASM({
 
        // Create a shallow copy of an event by copying its properties
        // to a new object.
        function snapshotEvent(event) {
 
            // Return non-events (and null) as-is
            if (!(event instanceof Event))
                return event;
 
            // Create event copy
            const copy = { isInstanceOfEvent: true };
            for (const key in event) {
                const value = event[key];
                copy[key] = typeof value === 'function' ? value.bind(event) : value;
            }
 
            return copy;
        }
 
        let index = $0;
        let control = Module.qtSuspendResumeControl;
        let handler = (arg) => {
 
            // Create a snapshot of the event for the queue. Browsers
            // may recycle the event objects once control returns which
            // means we can't store referenes to them in the queue.
            arg = snapshotEvent(arg);
 
            // Add event to event queue
            control.pendingEvents.push({
                index: index,
                arg: arg
            });
 
            // Handle the event based on instance state and asyncify flag
            if (control.exclusiveEventHandler > 0) {
                // In exclusive mode, resume on exclusive event handler match only
 
                if (index != control.exclusiveEventHandler)
                    return;
 
                const resume = control.resume;
                control.resume = null;
                resume();
            } else if (control.resume) {
                // The instance is suspended in processEvents(), resume and process the event
                const resume = control.resume;
                control.resume = null;
                resume();
            } else {
                if (control.asyncifyEnabled) {
                    // The instance is either not suspended or is supended outside of processEvents()
                    // (e.g. on emscripten_sleep()). Currently there is no way to determine
                    // which state the instance is in. Keep the event in the event queue to be
                    // processed on the next processEvents() call.
                    // FIXME: call event handler here if we can determine that the instance
                    // is not suspended.
                } else {
                    // The instance is not suspended, call the handler directly
                    Module.qtSendPendingEvents();
                }
            }
        };
        control.eventHandlers[index] = handler;
    }, index);
}
 
QWasmSuspendResumeControl::QWasmSuspendResumeControl()
{
#if QT_CONFIG(thread)
    Q_ASSERT(emscripten_is_main_runtime_thread());
#endif
    qtSuspendResumeControlClearJs();
    suspendResumeControlJs().set("asyncifyEnabled", qstdweb::haveAsyncify());
}
 
QWasmSuspendResumeControl::~QWasmSuspendResumeControl()
{
    if (!m_eventHandlers.empty())
        qWarning() << "QWasmSuspendResumeControl::~QWasmSuspendResumeControl - still remaining " << m_eventHandlers.size() << " handlers";
    qtSuspendResumeControlClearJs();
}
 
QWasmSuspendResumeControl *QWasmSuspendResumeControl::get()
{
    if (!s_suspendResumeControl)
        qFatal("QWasmSuspendResumeControl -- Object not created/destroyed");
 
    return s_suspendResumeControl;
}
 
// Registers a C++ event handler.
uint32_t QWasmSuspendResumeControl::registerEventHandler(std::function<void(val)> handler)
{
    static uint32_t i = 0;
    ++i;
    m_eventHandlers.emplace(i, std::move(handler));
    qtRegisterEventHandlerJs(i);
    return i;
}
 
// Removes a C++ event handler
void QWasmSuspendResumeControl::removeEventHandler(uint32_t index)
{
    m_eventHandlers.erase(index);
    suspendResumeControlJs()["eventHandlers"].set(index, val::null());
}
 
// Returns the JS event handler for the given index
val QWasmSuspendResumeControl::jsEventHandlerAt(uint32_t index)
{
    return suspendResumeControlJs()["eventHandlers"][index];
}
 
emscripten::val QWasmSuspendResumeControl::suspendResumeControlJs()
{
    return val::module_property("qtSuspendResumeControl");
}
 
// Suspends the calling thread.
void QWasmSuspendResumeControl::suspend()
{
    if (!qstdweb::canBlockCallingThread()) {
        qFatal("Suspending the main thread requires asyncify or JSPI; "
               "see the Qt for WebAssembly documentation for how to enable.");
    }
    qtSuspendJs();
}
 
void QWasmSuspendResumeControl::suspendExclusive(QList<uint32_t> eventHandlerIndices)
{
    if (!qstdweb::canBlockCallingThread()) {
        qFatal("Suspending the main thread requires asyncify or JSPI; "
               "see the Qt for WebAssembly documentation for how to enable.");
    }
 
    m_eventFilter = [eventHandlerIndices](int handler) {
        return eventHandlerIndices.contains(handler);
    };
 
    suspendResumeControlJs().set("exclusiveEventHandler", eventHandlerIndices.back());
    qtSuspendJs();
}
 
// Sends any pending events. Returns the number of sent events.
int QWasmSuspendResumeControl::sendPendingEvents()
{
#if QT_CONFIG(thread)
    Q_ASSERT(emscripten_is_main_runtime_thread());
#endif
    emscripten::val control = suspendResumeControlJs();
    emscripten::val pendingEvents = control["pendingEvents"];
 
    int count = 0;
    for (int i = 0; i < pendingEvents["length"].as<int>();) {
        if (!m_eventFilter(pendingEvents[i]["index"].as<int>())) {
            ++i;
        } else {
            // Grab one event (handler and arg), and call it
            emscripten::val event = pendingEvents[i];
            pendingEvents.call<void>("splice", i, 1);
 
            auto it = m_eventHandlers.find(event["index"].as<int>());
            if (it != m_eventHandlers.end()) {
                setCurrentEvent(event["arg"]);
                it->second(currentEvent());
                setCurrentEvent(emscripten::val::undefined());
            }
            ++count;
        }
    }
 
    if (control["exclusiveEventHandler"].as<int>() > 0) {
        control.set("exclusiveEventHandler", 0);
        m_eventFilter = [](int) { return true;};
    }
    return count;
}
 
void qtSendPendingEvents()
{
    if (s_suspendResumeControl)
        s_suspendResumeControl->sendPendingEvents();
}
 
EMSCRIPTEN_BINDINGS(qtSuspendResumeControl) {
    emscripten::function("qtSendPendingEvents", qtSendPendingEvents QT_WASM_EMSCRIPTEN_ASYNC);
}
 
//
// The EventCallback class registers a callback function for an event on an html element.
//
QWasmEventHandler::QWasmEventHandler(emscripten::val element, const std::string &name, std::function<void(emscripten::val)> handler)
:m_element(element)
,m_name(name)
{
    QWasmSuspendResumeControl *suspendResume = QWasmSuspendResumeControl::get();
    m_eventHandlerIndex = suspendResume->registerEventHandler(std::move(handler));
    m_element.call<void>("addEventListener", m_name, suspendResume->jsEventHandlerAt(m_eventHandlerIndex));
}
 
QWasmEventHandler::~QWasmEventHandler()
{
    // Do nothing if this instance is default-constructed, or was moved from.
    if (m_element.isUndefined())
        return;
 
    QWasmSuspendResumeControl *suspendResume = QWasmSuspendResumeControl::get();
    m_element.call<void>("removeEventListener", m_name, suspendResume->jsEventHandlerAt(m_eventHandlerIndex));
    suspendResume->removeEventHandler(m_eventHandlerIndex);
}
 
QWasmEventHandler::QWasmEventHandler(QWasmEventHandler&& other) noexcept
:m_element(std::move(other.m_element))
,m_name(std::move(other.m_name))
,m_eventHandlerIndex(other.m_eventHandlerIndex)
{
    other.m_element = emscripten::val();
    other.m_name = emscripten::val();
    other.m_eventHandlerIndex = 0;
}
 
QWasmEventHandler& QWasmEventHandler::operator=(QWasmEventHandler&& other) noexcept
{
    m_element = std::move(other.m_element);
    other.m_element = emscripten::val();
    m_name = std::move(other.m_name);
    other.m_name = emscripten::val();
    m_eventHandlerIndex = other.m_eventHandlerIndex;
    other.m_eventHandlerIndex = 0;
    return *this;
}
 
//
// The QWasmTimer class creates a native single-shot timer. The event handler is provided in the
// constructor and can be reused: each call setTimeout() sets a new timeout, though with the
// limitiation that there can be only one timeout at a time. (Setting a new timer clears the
// previous one).
//
QWasmTimer::QWasmTimer(QWasmSuspendResumeControl *suspendResume, std::function<void()> handler)
    :m_suspendResume(suspendResume)
{
    auto wrapper = [handler = std::move(handler), this](val argument) {
        Q_UNUSED(argument); // no argument for timers
        if (!m_timerId)
            return; // timer was cancelled
        m_timerId = 0;
        handler();
    };
 
    m_handlerIndex = m_suspendResume->registerEventHandler(std::move(wrapper));
}
 
QWasmTimer::~QWasmTimer()
{
    clearTimeout();
    // We lack a test that checks validity of m_suspendResume
    m_suspendResume->removeEventHandler(m_handlerIndex);
}
 
void QWasmTimer::setTimeout(std::chrono::milliseconds timeout)
{
    Q_ASSERT(m_suspendResume == QWasmSuspendResumeControl::get());
    if (hasTimeout())
        clearTimeout();
    val jsHandler = QWasmSuspendResumeControl::get()->jsEventHandlerAt(m_handlerIndex);
    using ArgType = double; // emscripten::val::call() does not support int64_t
    ArgType timoutValue = static_cast<ArgType>(timeout.count());
    ArgType timerId = val::global("window").call<ArgType>("setTimeout", jsHandler, timoutValue);
    m_timerId = static_cast<int64_t>(std::round(timerId));
}
 
bool QWasmTimer::hasTimeout()
{
    return m_timerId > 0;
}
 
void QWasmTimer::clearTimeout()
{
    val::global("window").call<void>("clearTimeout", double(m_timerId));
    m_timerId = 0;
}
 
//
// QWasmAnimationFrameMultiHandler
//
// Multiplexes multiple animate and draw callbacks to a single native requestAnimationFrame call.
// Animate callbacks are called before draw callbacks to ensure animations are advanced before drawing.
//
QWasmAnimationFrameMultiHandler::QWasmAnimationFrameMultiHandler()
{
    auto wrapper = [this](val arg) {
        handleAnimationFrame(arg.as<double>());
    };
    m_handlerIndex = QWasmSuspendResumeControl::get()->registerEventHandler(wrapper);
}
 
QWasmAnimationFrameMultiHandler::~QWasmAnimationFrameMultiHandler()
{
    cancelAnimationFrameRequest();
    QWasmSuspendResumeControl::get()->removeEventHandler(m_handlerIndex);
}
 
Q_GLOBAL_STATIC(QWasmAnimationFrameMultiHandler, s_animationFrameHandler);
QWasmAnimationFrameMultiHandler *QWasmAnimationFrameMultiHandler::instance()
{
    return s_animationFrameHandler();
}
 
// Registers a permanent animation callback. Call unregisterAnimateCallback() to unregister
uint32_t QWasmAnimationFrameMultiHandler::registerAnimateCallback(Callback callback)
{
    uint32_t handle = ++m_nextAnimateHandle;
    m_animateCallbacks[handle] = std::move(callback);
    ensureAnimationFrameRequested();
    return handle;
}
 
// Registers a single-shot draw callback.
uint32_t QWasmAnimationFrameMultiHandler::registerDrawCallback(Callback callback)
{
    uint32_t handle = ++m_nextDrawHandle;
    m_drawCallbacks[handle] = std::move(callback);
    ensureAnimationFrameRequested();
    return handle;
}
 
void QWasmAnimationFrameMultiHandler::unregisterAnimateCallback(uint32_t handle)
{
    m_animateCallbacks.erase(handle);
    if (m_animateCallbacks.empty() && m_drawCallbacks.empty())
        cancelAnimationFrameRequest();
}
 
void QWasmAnimationFrameMultiHandler::unregisterDrawCallback(uint32_t handle)
{
    m_drawCallbacks.erase(handle);
    if (m_animateCallbacks.empty() && m_drawCallbacks.empty())
        cancelAnimationFrameRequest();
}
 
void QWasmAnimationFrameMultiHandler::handleAnimationFrame(double timestamp)
{
    m_requestId = -1;
 
    // Advance animations. Copy the callbacks list in case callbacks are
    // unregistered during iteration
    auto animateCallbacksCopy = m_animateCallbacks;
    for (const auto &pair : animateCallbacksCopy)
        pair.second(timestamp);
 
    // Draw the frame. Note that draw callbacks are cleared after each
    // frame, matching QWindow::requestUpdate() behavior. Copy the callbacks
    // list in case new callbacks are registered while drawing the frame
    auto drawCallbacksCopy = m_drawCallbacks;
    m_drawCallbacks.clear();
    for (const auto &pair : drawCallbacksCopy)
        pair.second(timestamp);
 
    // Request next frame if there are still callbacks registered
    if (!m_animateCallbacks.empty() || !m_drawCallbacks.empty())
        ensureAnimationFrameRequested();
}
 
void QWasmAnimationFrameMultiHandler::ensureAnimationFrameRequested()
{
    if (m_requestId != -1)
        return;
 
    using ReturnType = double;
    val handler = QWasmSuspendResumeControl::get()->jsEventHandlerAt(m_handlerIndex);
    m_requestId = int64_t(val::global("window").call<ReturnType>("requestAnimationFrame", handler));
}
 
void QWasmAnimationFrameMultiHandler::cancelAnimationFrameRequest()
{
    if (m_requestId == -1)
        return;
 
    val::global("window").call<void>("cancelAnimationFrame", double(m_requestId));
    m_requestId = -1;
}