Clock/Platform: Add currentMillis() analogue to currentNanos(), returning current monotonic milliseconds **since start of this application**

Also added TSPrinter, a simple millisecond timestamp prepending `print*()` wrapper for a {@link PrintStream}.

Test coverage via TestClock01.

5 files changed, 277 insertions, 9 deletions

diff --git a/src/java/com/jogamp/common/os/Clock.java b/src/java/com/jogamp/common/os/Clock.java
index 9380442..8e9f99d 100644
--- a/src/java/com/jogamp/common/os/Clock.java
+++ b/src/java/com/jogamp/common/os/Clock.java
@@ -144,8 +144,23 @@ public class Clock {
     }
 
     /**
-     * Returns current monotonic time in milliseconds.
-     *
+     * Returns current monotonic milliseconds since start of this application.
+     * <p>
+     * Monotonic time shall be used for high-performance measurements of durations,
+     * since the underlying OS shall support fast calls.
+     * </p>
+     * @see #getMonotonicStartupTime()
+     * @see #currentNanos()
+     * @see #getMonotonicNanos()
+     */
+    public static native long currentMillis();
+
+    /**
+     * Returns the unix based current monotonic time in milliseconds.
+     * <p>
+     * Monotonic time shall be used for high-performance measurements of durations,
+     * since the underlying OS shall support fast calls.
+     * </p>
      * @see #getMonotonicStartupTime()
      * @see #currentNanos()
      * @see #getMonotonicNanos()
diff --git a/src/java/com/jogamp/common/os/Platform.java b/src/java/com/jogamp/common/os/Platform.java
index ffea42c..206b7f8 100644
--- a/src/java/com/jogamp/common/os/Platform.java
+++ b/src/java/com/jogamp/common/os/Platform.java
@@ -521,7 +521,23 @@ public class Platform extends PlatformPropsImpl {
     //
 
     /**
-     * Returns the unix based current time in milliseconds, see {@link Clock#currentTimeMillis()}.
+     * Returns current monotonic milliseconds since start of this application.
+     * <p>
+     * Monotonic time shall be used for high-performance measurements of durations,
+     * since the underlying OS shall support fast calls.
+     * </p>
+     * @see Clock#currentMillis()
+     */
+    public static long currentMillis() {
+        return Clock.currentMillis();
+    }
+
+    /**
+     * Returns the unix based current monotonic time in milliseconds.
+     * <p>
+     * Monotonic time shall be used for high-performance measurements of durations,
+     * since the underlying OS shall support fast calls.
+     * </p>
      * @see Clock#currentTimeMillis()
      */
     public static long currentTimeMillis() {
diff --git a/src/java/com/jogamp/common/util/TSPrinter.java b/src/java/com/jogamp/common/util/TSPrinter.java
new file mode 100644
index 0000000..43b4f4f
--- /dev/null
+++ b/src/java/com/jogamp/common/util/TSPrinter.java
@@ -0,0 +1,95 @@
+/**
+ * Author: Sven Gothel <[email protected]>
+ * Copyright (c) 2022-2023 Gothel Software e.K.
+ * Copyright (c) 2022-2023 JogAmp Community.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.jogamp.common.util;
+
+import java.io.PrintStream;
+
+import com.jogamp.common.os.Clock;
+
+/** A simple millisecond timestamp prepending `print*()` wrapper for a {@link PrintStream}.  */
+public class TSPrinter {
+    private static TSPrinter err;
+    private static TSPrinter out;
+
+    public static synchronized TSPrinter stderr() {
+        if( null == err ) {
+            err = new TSPrinter(System.err);
+        }
+        return err;
+    }
+    public static synchronized TSPrinter stdout() {
+        if( null == out ) {
+            out = new TSPrinter(System.out);
+        }
+        return out;
+    }
+
+    private final PrintStream parent;
+
+    public TSPrinter(final PrintStream parent) {
+        this.parent = parent;
+    }
+
+    public static void printf(final PrintStream out, final long millis, final String format, final Object ... args) {
+        out.printf("[%,9d] ", millis);
+        out.printf(format, args);
+    }
+    public static void printf(final PrintStream out, final String format, final Object ... args) {
+        printf(out, Clock.currentMillis(), format, args);
+    }
+    public void printf(final long millis, final String format, final Object ... args) {
+        printf(parent, millis, format, args);
+    }
+    public void printf(final String format, final Object ... args) {
+        printf(parent, Clock.currentMillis(), format, args);
+    }
+
+    public static void print(final PrintStream out, final long millis, final String msg) {
+        out.printf("[%,9d] %s", millis, msg);
+    }
+    public static void print(final PrintStream out, final String msg) {
+        print(out, Clock.currentMillis(), msg);
+    }
+    public void print(final long millis, final String msg) {
+        print(parent, millis, msg);
+    }
+    public void print(final String msg) {
+        print(parent, Clock.currentMillis(), msg);
+    }
+
+    public static void println(final PrintStream out, final long millis, final String msg) {
+        out.printf("[%,9d] %s%n", millis, msg);
+    }
+    public static void println(final PrintStream out, final String msg) {
+        println(out, Clock.currentMillis(), msg);
+    }
+    public void println(final long millis, final String msg) {
+        println(parent, millis, msg);
+    }
+    public void println(final String msg) {
+        println(parent, Clock.currentMillis(), msg);
+    }
+
+}
diff --git a/src/junit/com/jogamp/common/os/TestClock01.java b/src/junit/com/jogamp/common/os/TestClock01.java
new file mode 100644
index 0000000..1014419
--- /dev/null
+++ b/src/junit/com/jogamp/common/os/TestClock01.java
@@ -0,0 +1,113 @@
+/**
+ * Author: Sven Gothel <[email protected]>
+ * Copyright (c) 2022-2023 Gothel Software e.K.
+ * Copyright (c) 2022-2023 JogAmp Community.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package com.jogamp.common.os;
+
+import java.time.Instant;
+import java.time.ZoneOffset;
+import java.time.temporal.ChronoUnit;
+
+import org.junit.Assert;
+import org.junit.FixMethodOrder;
+import org.junit.Test;
+import org.junit.runners.MethodSorters;
+
+import com.jogamp.common.util.TSPrinter;
+import com.jogamp.junit.util.JunitTracer;
+
+@FixMethodOrder(MethodSorters.NAME_ASCENDING)
+public class TestClock01 extends JunitTracer {
+    TSPrinter logout = TSPrinter.stderr();
+
+    @Test
+    public void test00()  {
+        Platform.initSingleton();
+        TSPrinter.print(System.err, "test00\n");
+
+        final Instant m_t0 = Instant.ofEpochMilli(Clock.currentTimeMillis());
+        final Instant m_t1 = Clock.getMonotonicTime();
+        final Instant w_t2 = Instant.ofEpochSecond(Clock.wallClockSeconds());
+        final Instant w_t3 = Clock.getWallClockTime();
+
+        try {
+            Thread.sleep(100);
+        } catch (final InterruptedException e) { }
+
+        final Instant m_t0_b = Instant.ofEpochMilli(Clock.currentTimeMillis());
+        final Instant m_t1_b = Clock.getMonotonicTime();
+        final Instant w_t2_b = Instant.ofEpochSecond(Clock.wallClockSeconds());
+        final Instant w_t3_b = Clock.getWallClockTime();
+
+        final long m_t0_d = m_t0.until(m_t0_b, ChronoUnit.MILLIS);
+        final long m_t1_d = m_t1.until(m_t1_b, ChronoUnit.MILLIS);
+        final long w_t2_d = w_t2.until(w_t2_b, ChronoUnit.MILLIS);
+        final long w_t3_d = w_t3.until(w_t3_b, ChronoUnit.MILLIS);
+
+        TSPrinter.printf(System.err, "mono t0 %s, %d ms\n", m_t0.atZone(ZoneOffset.UTC), m_t0_d);
+        TSPrinter.printf(System.err, "mono t1 %s, %d ms\n", m_t1.atZone(ZoneOffset.UTC), m_t1_d);
+        TSPrinter.printf(System.err, "wall t2 %s, %d ms\n", w_t2.atZone(ZoneOffset.UTC), w_t2_d);
+        TSPrinter.printf(System.err, "wall t3 %s, %d ms\n", w_t3.atZone(ZoneOffset.UTC), w_t3_d);
+
+        final long td_min = 50;
+        final long td_max = 150;
+        Assert.assertTrue( td_min <= m_t0_d );
+        Assert.assertTrue( td_max >= m_t0_d );
+
+        Assert.assertTrue( td_min <= m_t1_d );
+        Assert.assertTrue( td_max >= m_t1_d );
+
+        Assert.assertTrue( 0      <= w_t2_d ); // sec granularity only
+        Assert.assertTrue( 1000   >= w_t2_d );
+
+        Assert.assertTrue( td_min <= w_t3_d );
+        Assert.assertTrue( td_max >= w_t3_d );
+    }
+
+    @Test
+    public void test01() {
+        TSPrinter.print(System.err, "test01\n");
+        final long tr0 = Clock.currentMillis(); // relative
+        final long ta0 = Clock.currentTimeMillis(); // absolute
+        final long td_ar = ta0 - tr0;
+        try {
+            Thread.sleep(100);
+        } catch (final InterruptedException e) { }
+        final long td_r = Clock.currentMillis() - tr0; // relative
+        final long td_a = Clock.currentTimeMillis() - ta0; // absolute
+
+        TSPrinter.printf(System.err, "mono ts ms: tr0 rel %d, ta0 abs %d, diff %d\n", tr0, ta0, td_ar);
+        TSPrinter.printf(System.err, "mono td ms: tr* rel %d, ta* abs %d\n", td_r, td_a);
+
+        Assert.assertTrue(td_ar >= 0);
+        Assert.assertTrue(Math.abs(td_r - 100) < 10); // generous 10% error margin
+        Assert.assertTrue(Math.abs(td_a - 100) < 10); // ditto
+    }
+
+    public static void main(final String args[]) {
+        final String tstname = TestClock01.class.getName();
+        org.junit.runner.JUnitCore.main(tstname);
+    }
+
+}
diff --git a/src/native/common/jau_sys_Clock.c b/src/native/common/jau_sys_Clock.c
index e8a7210..ada091f 100644
--- a/src/native/common/jau_sys_Clock.c
+++ b/src/native/common/jau_sys_Clock.c
@@ -133,13 +133,42 @@ Java_com_jogamp_common_os_Clock_currentNanos(JNIEnv *env, jclass clazz) {
 
     struct timespec t = { .tv_sec = 0, .tv_nsec = 0 };
     if( 0 == clock_gettime(CLOCK_MONOTONIC, &t) ) {
-        struct timespec d = { .tv_sec = t.tv_sec - startup_t.tv_sec,
-                              .tv_nsec = t.tv_nsec - startup_t.tv_nsec };
-        if ( 0 > d.tv_nsec ) {
-            d.tv_nsec += NanoPerSec;
-            d.tv_sec  -= 1;
+        t.tv_sec -= startup_t.tv_sec;
+        t.tv_nsec -= startup_t.tv_nsec;
+        if ( 0 > t.tv_nsec ) {
+            t.tv_nsec += NanoPerSec;
+            t.tv_sec  -= 1;
         }
-        return (jlong) ( (int64_t)d.tv_sec * NanoPerSec + (int64_t)d.tv_nsec );
+        return (jlong) ( (int64_t)t.tv_sec * NanoPerSec + (int64_t)t.tv_nsec );
+    } else {
+        return 0;
+    }
+}
+
+/**
+ * See <http://man7.org/linux/man-pages/man2/clock_gettime.2.html>
+ * <p>
+ * Regarding avoiding kernel via VDSO,
+ * see <http://man7.org/linux/man-pages/man7/vdso.7.html>,
+ * clock_gettime seems to be well supported at least on kernel >= 4.4.
+ * Only bfin and sh are missing, while ia64 seems to be complicated.
+ */
+JNIEXPORT jlong JNICALL
+Java_com_jogamp_common_os_Clock_currentMillis(JNIEnv *env, jclass clazz) {
+    (void)env;
+    (void)clazz;
+
+    struct timespec t = { .tv_sec = 0, .tv_nsec = 0 };
+    if( 0 == clock_gettime(CLOCK_MONOTONIC, &t) ) {
+        t.tv_sec -= startup_t.tv_sec;
+        t.tv_nsec -= startup_t.tv_nsec;
+        if ( 0 > t.tv_nsec ) {
+            t.tv_nsec += NanoPerSec;
+            t.tv_sec  -= 1;
+        }
+        int64_t res = (int64_t)t.tv_sec  * MilliPerOne +
+                      (int64_t)t.tv_nsec / NanoPerMilli;
+        return (jlong)res;
     } else {
         return 0;
     }