Skip to content

Feature: Expose thread-safe C++ API for WebSocket binary sends from background threads #436

@dipterix

Description

@dipterix

Summary

We'd like to send WebSocket binary messages from a C++ background thread (via an Rcpp package) without requiring the main R thread to be idle. Currently the only path is sendWSMessage(), which begins with ASSERT_MAIN_THREAD() and therefore cannot be called from any thread other than R's main thread. This makes it impossible to stream high-frequency data to a browser without being blocked by R's event loop.


Motivation

Consider a real-time multichannel signal streaming use case — for example, 100 channels at 2000 Hz displayed in a Shiny app. The current data pipeline looks like this:

[acquisition / callr bg process]
       ↓  (shared memory)
[Shiny main process]
       ↓  later::later() fires → session$sendBinaryMessage()
       ↓  sendWSMessage() → ASSERT_MAIN_THREAD() → background_queue->push()
       ↓  I/O thread writes to socket
[browser]

The actual socket write already happens off the main R thread via background_queue. The ASSERT_MAIN_THREAD() guard in the Rcpp-exported sendWSMessage only protects the thin dispatch layer — the byte copy and queue push — which are microsecond-level operations. However, the requirement that this dispatch happen on the main R thread means that any blocking R operation (a reactive computation, a database query, a Sys.sleep) will stall the stream, since later::later() callbacks only fire when the R call stack is empty or run_now() is called explicitly.

If we could push directly to background_queue from a C++ thread in a downstream Rcpp package — bypassing the main-thread assertion — the send path would be fully decoupled from R's scheduler:

[C++ background thread in downstream Rcpp package]
       ↓  reads from lock-free ring buffer (e.g. bigmemory)
       ↓  encodes Int16 raw bytes
       ↓  pushes directly to httpuv's background_queue
       ↓  I/O thread writes to socket
[browser]

R blocking would become completely irrelevant to the stream.


What already exists

  • background_queue is a file-scoped static CallbackQueue* in src/httpuv.cpp — not accessible from outside the translation unit.
  • httpuv exposes no public C++ headers in inst/include/.
  • The WebSocketConnection class and the queue push pattern are entirely internal.

Prior art: The later package solves an analogous problem by exposing its C++ event loop API via inst/include/later_api.h, allowing downstream Rcpp packages to schedule callbacks onto the correct thread without going through R. httpuv could follow the same pattern.


Proposed API

A minimal addition to a new inst/include/httpuv_api.h:

namespace httpuv {

// Thread-safe. May be called from any thread.
// Schedules a binary WebSocket send on the I/O background thread.
// conn_xptr: the SEXP XPtr<shared_ptr<WebSocketConnection>> from R
// data:      pointer to raw bytes (copied internally before return)
// len:       number of bytes
// Returns false if the connection is closed or the queue is unavailable.
bool send_binary_threadsafe(SEXP conn_xptr, const char* data, size_t len);

} // namespace httpuv

Internally this would do exactly what sendWSMessage does after the assert — copy bytes into a heap-allocated vector<char> and push the callback and deleter onto background_queue — but without the ASSERT_MAIN_THREAD() guard, since background_queue->push() is already designed for cross-thread use (it signals a uv_async_t).


Safety considerations

  • background_queue->push() is already thread-safe by design — it uses uv_async_send internally.
  • The byte copy (new std::vector<char>(data, data + len)) is safe on any thread as it only allocates from the heap.
  • The conn_xptr would be captured as a shared_ptr copy (not a raw pointer), keeping the connection alive for the duration of the callback.
  • The ASSERT_MAIN_THREAD() guard would remain on the existing sendWSMessage R-level export. This new function is purely additive.

Alternatives considered

I have the following alternatives, each has its own problems. I figured out the most straightforward way is to let httpuv expose its C++ interface directly.

Alternative Why it falls short
Second httpuv server on a separate port Requires the client to open a second WebSocket connection — not always possible behind single-port proxies or firewalls
later::later() loop Still requires R to be idle; any blocking R operation stalls the stream

Minimum viable ask

Even just making background_queue accessible as an opaque handle through a thin C API — similar to how later exposes later::later_api::Later — would be sufficient. A full public object model is not needed: just the ability to push a pre-encoded binary payload onto the I/O queue from a C++ thread without touching R.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions