Data Buffering & Emission
Relevant source files
The following files were used as context for generating this wiki page:
- android/src/main/kotlin/app/tauri/serialplugin/manager/BufferedEmitter.kt
- android/src/main/kotlin/app/tauri/serialplugin/manager/SerialByteAccumulator.kt
- android/src/main/kotlin/app/tauri/serialplugin/manager/SerialDataEmitFields.kt
- android/src/main/kotlin/app/tauri/serialplugin/SerialPlugin.kt
- guest-js/index.ts
- CHANGELOG.md
- android/src/test/kotlin/app/tauri/serialplugin/manager/SerialDataEmitFieldsTest.kt
The Data Buffering & Emission system is a performance-oriented architecture within the Tauri Serial Plugin designed to manage high-frequency serial data streams on Android. Its primary purpose is to coalesce incoming data chunks into batches before emitting them to the JavaScript guest side, thereby reducing the overhead and backpressure on the WebView and the IPC (Inter-Process Communication) layer.
This system ensures that even when a serial device transmits data at a very high rate, the application remains responsive by controlling the frequency of "serialData" events. Users can configure this behavior via a specific flush interval, ensuring a balance between real-time data visibility and system stability.
Core Architecture
The buffering logic resides primarily on the Android native side, utilizing a scheduled execution model to manage data flow.
BufferedEmitter
The BufferedEmitter is the central coordinator for data batching. It utilizes a ScheduledExecutorService to trigger data flushes at a fixed rate defined by the flushIntervalMs.
- Lifecycle Management: It initializes a single-thread scheduled executor named
serial-emit-[path]as a daemon thread. - Data Coalescing: When new bytes are received via
addData(ByteArray), they are appended to an internalSerialByteAccumulator. - Scheduled Flushing: The
flushOnce()method is called at every interval. It drains the accumulator and converts the bytes into aJSObjectfor emission. - Cleanup: The
stop()method ensures that any remaining data in the buffer is flushed one last time before the scheduler is shut down.
Sources: android/src/main/kotlin/app/tauri/serialplugin/manager/BufferedEmitter.kt:14-44, android/src/main/kotlin/app/tauri/serialplugin/manager/BufferedEmitter.kt:56-74
SerialByteAccumulator
This component provides a thread-safe mechanism for storing raw bytes until they are ready for emission. It supports atomic operations to append data and "drain" the current buffer, which returns the accumulated bytes and clears the storage for the next cycle.
Sources: android/README.md, CHANGELOG.md
Data Flow Diagram
The following diagram illustrates the path of data from the hardware level to the JavaScript frontend.
The diagram shows how the BufferedEmitter acts as a gatekeeper, preventing the IPC layer from being overwhelmed by hardware-level interrupts.
Data Structure & Payload
The system uses specific structures to ensure data integrity during the transition from Kotlin ByteArray to JavaScript String.
SerialDataEmitFields
This internal data class mirrors the fields sent to the plugin event. It preserves both UTF-8 strings and binary bytes (including NUL bytes) by mapping the raw chunk to a technical string representation.
| Field | Type | Description |
|---|---|---|
path | String | The unique path of the serial port. |
dataAsString | String | The raw bytes converted to a string representation. |
size | Int | The actual number of bytes in the chunk. |
Sources: android/src/main/kotlin/app/tauri/serialplugin/manager/SerialDataEmitFields.kt:10-14, android/src/test/kotlin/app/tauri/serialplugin/manager/SerialDataEmitFieldsTest.kt:19-27
Configuration and API
The buffering behavior is controlled during the initialization of the listening process.
Listening Configuration
When calling startListening, the user can provide serialDataFlushIntervalMs. On the native side, this value is clamped between 10ms and 2000ms to ensure system stability.
@InvokeArg
class StartListenArgs {
lateinit var path: String
/** Flush interval for batched serialData events (ms). Default 100; clamped 10–2000 on native side. */
var serialDataFlushIntervalMs: Long = 100L
}
Sources: android/src/main/kotlin/app/tauri/serialplugin/SerialPlugin.kt:83-87, android/src/main/kotlin/app/tauri/serialplugin/SerialPlugin.kt:335-343
JavaScript Options
In the Guest JS API, the SerialportOptions and SerialPortConfig types allow developers to specify the flush interval.
| Parameter | Type | Default | Description |
|---|---|---|---|
serialDataFlushIntervalMs | number | 100 | The frequency (in ms) at which batched data is sent to JS. |
Sources: guest-js/index.ts:28-30, guest-js/index.ts:103-111
Execution Logic
The sequence of data emission is handled asynchronously to the main UI thread to prevent blocking.
Resource Cleanup
To prevent memory leaks and stale background threads, the system implements a strict cleanup lifecycle. The SerialPlugin registers ActivityLifecycleCallbacks. When the host Activity is destroyed:
SerialPortManager.cleanup()is invoked.- Every
BufferedEmitteris stopped. - The
ScheduledExecutorServiceis shut down, and the system attempts a final flush of any remaining buffered data to ensure no data is lost during disconnection.
Sources: android/src/main/kotlin/app/tauri/serialplugin/SerialPlugin.kt:127-140, android/src/main/kotlin/app/tauri/serialplugin/manager/BufferedEmitter.kt:61-74
Summary
The Data Buffering & Emission system provides a robust solution for handling high-throughput serial communication on Android. By batching bytes into configurable time intervals and using thread-safe accumulators, the plugin avoids common pitfalls of cross-platform IPC like UI freezing and message loss, while maintaining a clean lifecycle tied to the Android Activity state.