Add Clock, implementing proper monotonic and wallclock time using Instant (sec + nsec), currentTimeMillis() is also monotonic now, reused by Platform. Dropped Platform.currentTimeMicros()

Clock and its implementation was copied from jaulibs, a spin-off from Direct-BT.

The implementation uses `clock_gettime(CLOCK_MONOTONIC, &t)` and is considered safe and high-performant
as it avoids a kernel call via VDSO (GNU/Linux).

2 files changed, 102 insertions, 20 deletions

diff --git a/src/java/com/jogamp/common/os/Clock.java b/src/java/com/jogamp/common/os/Clock.java
new file mode 100644
index 0000000..756d1d1
--- /dev/null
+++ b/src/java/com/jogamp/common/os/Clock.java
@@ -0,0 +1,96 @@
+/**
+ * Author: Sven Gothel <[email protected]>
+ * Copyright (c) 2020-2023 Gothel Software e.K.
+ * Copyright (c) 2020-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;
+
+public class Clock {
+    private static long t0;
+    static {
+        Platform.initSingleton(); // loads native gluegen_rt library
+        t0 = currentTimeMillis();
+    }
+
+    /**
+     * Returns current monotonic time since Unix Epoch `00:00:00 UTC on 1970-01-01`.
+     *
+     * Returned fraction_timespec is passing machine precision and range of the underlying native API.
+     *
+     * Monotonic time shall be used for high-performance measurements of durations,
+     * since the underlying OS shall support fast calls.
+     *
+     * @see getWallClockTime()
+     */
+    public static Instant getMonotonicTime() {
+        final long[/*2*/] val = { 0, 0 };
+        getMonotonicTimeImpl(val);
+        return Instant.ofEpochSecond(val[0], val[1]);
+    }
+    private static native void getMonotonicTimeImpl(final long[/*2*/] val);
+
+    /**
+     * Returns current wall-clock real-time since Unix Epoch `00:00:00 UTC on 1970-01-01`.
+     *
+     * Returned Instant is passing machine precision and range of the underlying native API.
+     *
+     * Wall-Clock time shall be used for accurate measurements of the actual time only,
+     * since the underlying OS unlikely supports fast calls.
+     *
+     * @see getMonotonicTime()
+     */
+    public static Instant getWallClockTime() {
+        final long[/*2*/] val = { 0, 0 };
+        getWallClockTimeImpl(val);
+        return Instant.ofEpochSecond(val[0], val[1]);
+    }
+    private static native void getWallClockTimeImpl(final long[/*2*/] val);
+
+    /**
+     * Returns current monotonic time in milliseconds.
+     */
+    public static native long currentTimeMillis();
+
+    /**
+     * Returns current wall-clock system `time of day` in seconds since Unix Epoch
+     * `00:00:00 UTC on 1 January 1970`.
+     */
+    public static native long wallClockSeconds();
+
+    /**
+     * Returns the startup time in monotonic time in milliseconds of the native module.
+     */
+    public static long startupTimeMillis() { return t0; }
+
+    /**
+     * Returns current elapsed monotonic time in milliseconds since module startup, see {@link #startupTimeMillis()}.
+     */
+    public static long elapsedTimeMillis() { return currentTimeMillis() - t0; }
+
+    /**
+     * Returns elapsed monotonic time in milliseconds since module startup comparing against the given timestamp, see {@link #startupTimeMillis()}.
+     */
+    public static long elapsedTimeMillis(final long current_ts) { return current_ts - t0; }
+
+}
diff --git a/src/java/com/jogamp/common/os/Platform.java b/src/java/com/jogamp/common/os/Platform.java
index e6821ba..9c65596 100644
--- a/src/java/com/jogamp/common/os/Platform.java
+++ b/src/java/com/jogamp/common/os/Platform.java
@@ -1,5 +1,5 @@
 /**
- * Copyright 2010 JogAmp Community. All rights reserved.
+ * Copyright 2010-2023 JogAmp Community. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without modification, are
  * permitted provided that the following conditions are met:
@@ -521,26 +521,12 @@ public class Platform extends PlatformPropsImpl {
     //
 
     /**
-     * Returns the unix based current time in milliseconds, based on <code>gettimeofday(..)</code>.
-     * <p>
-     * This is an alternative to {@link System#currentTimeMillis()} and {@link System#nanoTime()}.
-     * While the named {@link System} methods do provide the required precision,
-     * <code>gettimeofday()</code> <i>also</i> guarantees time accuracy, i.e. update interval.
-     * </p>
-     * @see #currentTimeMicros()
-     */
-    public static native long currentTimeMillis();
-
-    /**
-     * Returns the unix based current time in microseconds, based on <code>gettimeofday(..)</code>.
-     * <p>
-     * This is an alternative to {@link System#currentTimeMillis()} and {@link System#nanoTime()}.
-     * While the named {@link System} methods do provide the required precision,
-     * <code>gettimeofday()</code> <i>also</i> guarantees time accuracy, i.e. update interval.
-     * </p>
-     * @see #currentTimeMillis()
+     * Returns the unix based current time in milliseconds, see {@link Clock#currentTimeMillis()}.
+     * @see Clock#currentTimeMillis()
      */
-    public static native long currentTimeMicros();
+    public static long currentTimeMillis() {
+        return Clock.currentTimeMillis();
+    }
 
     /**
      * Returns the estimated sleep jitter value in nanoseconds.