From 116784bd921fe21086a031e21941c873ed37b829 Mon Sep 17 00:00:00 2001
From: "hiddenalpha.ch" <23085769+hiddenalpha@users.noreply.github.com>
Date: Tue, 16 Jun 2026 11:16:36 +0200
Subject: [PATCH] Reduce busy-waiting CPU load in waitEvents()
The {@link #waitEvents()} implementation on non-windows systems
usually returns immediately. This is unfortunate for the callers
which want to await events in an infinite-loop. As doing so would
burn lot of CPU time.
For example: Code in `LinuxEventThread.run()` (in `SerialPort.java`)
calls us in an infinite-loop. As a work-around, it uses a (very) small
sleep, to not utilize a full CPU core all the time. But still, this
permanently wastes a lot of CPU cycles (that many, that it is a problem
in our production use-case). The win32 code uses `OVERLAPPED` structs
and `WaitSingleObject()` which already provide that kind of "wait"
mechanism.
Not perfect, but this patch at least provides a way to wait if nothing
is ready. That "feature" is off by default and can be enabled
individually.
Edit: TryFix CICD build
> - try fix error:
> "Compatibility with CMake < 3.5 has been removed from CMake."
> - Use an older ubuntu to broaden runtime compatiblity
> - try fix error:
> "Failed to locate 'make', requesting installation of command line developer tools"
> - Revert some non-working MacOS fixes
> - Explain why to use older ubuntu version
Squashed-From: b5072cabe2c9d8046a69f27f5f7e0ca7fe69da28
---
.github/workflows/build.yml | 8 ++-
CMakeLists.txt | 2 +-
src/main/cpp/_nix_based/jssc.cpp | 52 ++++++++++++++++++-
src/main/cpp/windows/jssc.cpp | 14 ++++-
src/main/java/jssc/SerialNativeInterface.java | 14 ++++-
src/main/java/jssc/SerialPort.java | 31 ++++++++++-
6 files changed, 112 insertions(+), 9 deletions(-)
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index e715240d8..5f70a7808 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -7,7 +7,11 @@ env:
jobs:
ubuntu:
- runs-on: [ubuntu-latest]
+ # Should be kept as old as possible to have better compatibility to
+ # runtime environments out in the whild. Newer runtimes are nearly
+ # always able to use libs linked with older toolchains. But not
+ # vice-versa.
+ runs-on: [ubuntu-22.04]
strategy:
fail-fast: false
matrix:
@@ -106,4 +110,4 @@ jobs:
java-version: 11
distribution: temurin
- - run: mvn -P "${{ matrix.profile }}" --batch-mode
\ No newline at end of file
+ - run: mvn -P "${{ matrix.profile }}" --batch-mode
diff --git a/CMakeLists.txt b/CMakeLists.txt
index a3b53cf49..8bc7d82b8 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 3.0)
+cmake_minimum_required(VERSION 3.5)
cmake_policy(SET CMP0048 NEW)
cmake_policy(SET CMP0042 NEW)
diff --git a/src/main/cpp/_nix_based/jssc.cpp b/src/main/cpp/_nix_based/jssc.cpp
index cab25db09..f9b463b34 100644
--- a/src/main/cpp/_nix_based/jssc.cpp
+++ b/src/main/cpp/_nix_based/jssc.cpp
@@ -907,13 +907,61 @@ const jint events[] = {INTERRUPT_BREAK,
//EV_RXFLAG, //Not supported
EV_TXEMPTY};
+
+/* backwards compatibility symbol. New callers should use `waitEvents2()`. */
+JNIEXPORT jobjectArray JNICALL
+Java_jssc_SerialNativeInterface_waitEvents( JNIEnv*env, jobject that, jlong portHandle ){
+ return Java_jssc_SerialNativeInterface_waitEvents2(env, that, portHandle, -1);
+}
+
+
/* OK */
/*
* Collecting data for EventListener class (Linux have no implementation of "WaitCommEvent" function from Windows)
*
*/
-JNIEXPORT jobjectArray JNICALL Java_jssc_SerialNativeInterface_waitEvents
- (JNIEnv *env, jobject, jlong portHandle) {
+JNIEXPORT jobjectArray JNICALL
+Java_jssc_SerialNativeInterface_waitEvents2(
+ JNIEnv*env, jobject, jlong portHandle, jint waitEventsTimeoutMs
+){
+ int err;
+
+ /* Code in `LinuxEventThread.run()` (in `SerialPort.java`) calls us
+ * in an infinite-loop. As a work-around, it uses a (very) small
+ * sleep, to not utilize a full CPU all the time. But still, this
+ * permanently wastes a lot of CPU cycles (that many, that it is a
+ * problem in our production use-case). The win32 code uses
+ * `OVERLAPPED` structs and `WaitSingleObject()` which already
+ * provide that kind of "wait" mechanism. But we do not have a
+ * win32-API here. As this impl here returns immediately, we'll
+ * first ask `poll()` (if available and enabled). This way we can
+ * "emulate" to actually wait if nothing is ready.
+ * See also JavaDoc of `SerialPort.setWaitEventsTimeoutMs(int)`. */
+ int const isFeatureEnabled = (waitEventsTimeoutMs >= 1);
+ if( isFeatureEnabled ){
+#if !HAVE_POLL
+ static unsigned cnt = 0;
+ if( ((cnt + 1) & 0xFFFF) == 1 ){
+ fprintf(stderr, "WARN: waitEventsTimeoutMs not available on your platform, as `poll()` not available.\n");
+ }
+#else
+ struct pollfd pfd = {0};
+ pfd.fd = portHandle;
+ pfd.events = POLLIN | POLLPRI | POLLRDHUP;
+ err = poll(&pfd, 1, waitEventsTimeoutMs);
+ if( err == -1 ) switch( errno ){
+ case EINTR:
+ /* Got interrupted by signal. Go report events we have so far. */
+ break;
+ default:
+ /* some error occurred. */
+ err = errno; /* bkup `errno` before calling into `FindClass()` */
+ jclass exClz = env->FindClass("java/lang/RuntimeException");
+ if( exClz ) env->ThrowNew(exClz, strerror(err));
+ return NULL;
+ }
+#endif
+ }
jclass intClass = env->FindClass("[I");
if( intClass == NULL ) return NULL;
diff --git a/src/main/cpp/windows/jssc.cpp b/src/main/cpp/windows/jssc.cpp
index 0f08718f0..88dc6afd5 100644
--- a/src/main/cpp/windows/jssc.cpp
+++ b/src/main/cpp/windows/jssc.cpp
@@ -447,12 +447,22 @@ JNIEXPORT jboolean JNICALL Java_jssc_SerialNativeInterface_sendBreak
return returnValue;
}
+
+/* backwards compatibility symbol. New callers should use `waitEvents2()`. */
+JNIEXPORT jobjectArray JNICALL
+Java_jssc_SerialNativeInterface_waitEvents( JNIEnv*env, jobject that, jlong portHandle ){
+ return Java_jssc_SerialNativeInterface_waitEvents2(env, that, portHandle, -1);
+}
+
+
/*
* Wait event
* portHandle - port handle
*/
-JNIEXPORT jobjectArray JNICALL Java_jssc_SerialNativeInterface_waitEvents
- (JNIEnv *env, jobject, jlong portHandle) {
+JNIEXPORT jobjectArray JNICALL
+Java_jssc_SerialNativeInterface_waitEvents2(
+ JNIEnv*env, jobject, jlong portHandle, jint/*unused on windows*/
+){
HANDLE hComm = (HANDLE)portHandle;
DWORD lpEvtMask = 0;
DWORD lpNumberOfBytesTransferred = 0;
diff --git a/src/main/java/jssc/SerialNativeInterface.java b/src/main/java/jssc/SerialNativeInterface.java
index 091dc3848..30e72e850 100644
--- a/src/main/java/jssc/SerialNativeInterface.java
+++ b/src/main/java/jssc/SerialNativeInterface.java
@@ -237,7 +237,19 @@ public static String getLibraryVersion() {
* @return Method returns two-dimensional array containing event types and their values
* (events[i][0] - event type, events[i][1] - event value).
*/
- public native int[][] waitEvents(long handle);
+ public int[][] waitEvents(long handle){ return waitEvents2(handle, -1); }
+
+ /**
+ * Wait events
+ *
+ * @param handle handle of opened port
+ *
+ * @param waitEventsTimeoutMs See {@link SerialPort#setWaitEventsTimeoutMs(int)}.
+ *
+ * @return Method returns two-dimensional array containing event types and their values
+ * (events[i][0] - event type, events[i][1] - event value).
+ */
+ public native int[][] waitEvents2(long handle, int waitEventsTimeoutMs);
/**
* Change RTS line state
diff --git a/src/main/java/jssc/SerialPort.java b/src/main/java/jssc/SerialPort.java
index a203bdec2..eac1c707b 100644
--- a/src/main/java/jssc/SerialPort.java
+++ b/src/main/java/jssc/SerialPort.java
@@ -41,6 +41,7 @@ public class SerialPort {
private final String portName;
private volatile boolean portOpened = false;
private boolean maskAssigned = false;
+ private int waitEventsTimeoutMs = -1;
//since 2.2.0 ->
private volatile Method methodErrorOccurred = null;
@@ -920,6 +921,34 @@ public boolean setFlowControlMode(int mask) throws SerialPortException {
return serialInterface.setFlowControlMode(portHandle, mask);
}
+ /**
+ * Reduce busy-waiting CPU load in {@link #waitEvents()}.
+ *
+ * (This is irrelevant for windows)
+ *
+ * The {@link #waitEvents()} implementation on non-windows systems
+ * usually returns immediately. This is unfortunate for the callers
+ * which want to await events in an infinite-loop. As doing so would
+ * burn lot of CPU time.
+ *
+ * This setting can be used to reduce that load. For regular
+ * incoming data events this does not cause any further delays.
+ * {@link #waitEvents()} still will reports most of the events as
+ * soon they become available, even before the specified timeout got
+ * reached.
+ *
+ * BUT BE AWARE: Enabling this might delay delivery of some special
+ * serial-events (like 'DCD line changed' or 'RI line changed') by
+ * the amount of time specified. So you have to decide yourself if
+ * you can/will afford this trade.
+ */
+ public void setWaitEventsTimeoutMs(int waitEventsTimeoutMs) {
+ if (waitEventsTimeoutMs <= 0) {
+ throw new IllegalArgumentException(String.valueOf(waitEventsTimeoutMs));
+ }
+ this.waitEventsTimeoutMs = waitEventsTimeoutMs;
+ }
+
/**
* Get flow control mode
*
@@ -951,7 +980,7 @@ public boolean sendBreak(int duration)throws SerialPortException {
}
private int[][] waitEvents() {
- return serialInterface.waitEvents(portHandle);
+ return serialInterface.waitEvents2(portHandle, waitEventsTimeoutMs);
}
/**