Reduce busy-waiting CPU load in waitEvents()

.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
+      - run: mvn -P "${{ matrix.profile }}" --batch-mode

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)
 

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;

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;

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
      * (<b>events[i][0] - event type</b>, <b>events[i][1] - event value</b>).
      */
-    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
+     * (<b>events[i][0] - event type</b>, <b>events[i][1] - event value</b>).
+     */
+    public native int[][] waitEvents2(long handle, int waitEventsTimeoutMs);
 
     /**
      * Change RTS line state

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