ENH: inline and extend clockValue, clockTime

- mostly wraps std::chrono so can inline much of it, which is potentially
  helpful when used for inner timings.

- add elapsedTime() method for direct cast to double and for
  naming similarity with wall-clock method.

Potential breaking change (minor):

- clockValue construct with a bool parameter is now simply tagged
  dispatch (value is ignored) and always queries the current clock
  value. This avoids needless branching.
  Since this constructor form has primarily been used internally (eg,
  clockTime), breakages in user code are not expected.

applications/test/clock/Test-clock.C

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018-2019 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -31,8 +31,8 @@ Description
 #include "OSspecific.H"
 #include "clock.H"
 #include "clockTime.H"
-#include "cpuTime.H"
 #include "clockValue.H"
+#include "cpuTime.H"
 
 using namespace Foam;
 
@@ -42,7 +42,7 @@ void testEpoch()
 {
     Info<< nl << "Test epoch" << nl;
 
-    ClockValue now(true);
+    const auto now = ClockValue::now();
 
     Info<< "epoch = " << now.str() << "  # day-hh:mm::ss" << nl
         << "epoch = " << now << nl;
@@ -73,7 +73,8 @@ void testElapsed()
         << "elapsed = " << a.elapsed().seconds() << nl
         << "elapsed = " << a.elapsed().str() << nl;
 
-    ClockValue b(true);
+    const ClockValue b(true);  // ClockValue::now()
+    Info<< "clockValue() " << b << nl;
 
     Info<< "(" << b << " - " << a << ") = " << (b - a) << nl;
     Info<< "(" << b << " + " << a << ") = " << (b + a) << nl;
@@ -86,7 +87,7 @@ void testElapsed()
 int main(int argc, char *argv[])
 {
     {
-        Foam::clock sysClock();
+        Foam::clock sysClock;
 
         Info<< "clock: date "  << clock::date() << nl
             << "clock: time "  << clock::clockTime() << nl
@@ -116,8 +117,8 @@ int main(int argc, char *argv[])
 
         Info<< "sleep 2..." << endl;
         sleep(2);
-        Info<< "elapsed   = " << clk.elapsedTime() << nl;
         Info<< "increment = " << clk.timeIncrement() << nl;
+        Info<< "elapsed   = " << clk.elapsedTime() << nl;
     }
 
     Info<< "End\n" << endl;

src/OpenFOAM/Make/files

@@ -4,7 +4,6 @@ global/global.Cver
 global/argList/argList.C
 global/argList/argListHelp.C
 global/clock/clock.C
-global/clockTime/clockTime.C
 global/clockValue/clockValue.C
 global/cpuTime/cpuTimeCxx.C
 global/debug/simpleObjectRegistry.C

src/OpenFOAM/global/clock/clock.C

@@ -128,7 +128,7 @@ double Foam::clock::elapsedClockTime() const
 
 double Foam::clock::clockTimeIncrement() const
 {
-    const value_type prev(last_);
+    const auto prev(last_);
 
     last_ = getTime();
     return ::difftime(last_, prev);

src/OpenFOAM/global/clock/clock.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -52,50 +52,56 @@ namespace Foam
 
 class clock
 {
-    // Private data
+    // Private Data
 
-        //- Time structure used
+        //- Time point at start (in seconds)
-        typedef time_t value_type;
+        time_t start_;
-
-        //- Start time in seconds, at the time of construction
-        value_type start_;
 
         //- Last time when elapsedClockTime or clockTimeIncrement was called
-        mutable value_type last_;
+        mutable time_t last_;
+
 
 public:
 
     // Constructors
 
-        //- Construct null, storing the start time
+        //- Construct with the current clock time for the start point
         clock();
 
 
-    // Static Member Functions
+    // Low-level Member Functions
 
         //- Get the current clock time in seconds
         static time_t getTime();
 
-        //- Return the current wall-clock date as a raw struct
+        //- The current wall-clock date as a raw struct
+        //  \deprecated(2020-05) may be removed in future versions
         static const struct tm rawDate();
 
-        //- Return the current wall-clock date/time as a string
+
-        //  format according to ISO-8601 (yyyy-mm-ddThh:mm:ss)
+    // Static Member Functions
+
+        //- The current wall-clock date/time (in local time) as a string
+        //- in ISO-8601 format (yyyy-mm-ddThh:mm:ss).
+        //  Without time-zone information.
         static std::string dateTime();
 
-        //- Return the current wall-clock date as a string
+        //- The current wall-clock date as a string formatted as
+        //- (MON dd yyyy), where MON is Jan, Feb, etc.
         static std::string date();
 
-        //- Return the current wall-clock time as a string
+        //- The current wall-clock (in local time) as a string formatted as
+        //- as (hh:mm:ss).
+        //  Without time-zone information.
         static std::string clockTime();
 
 
     // Member Functions
 
-        //- Returns wall-clock time from clock instantiation
+        //- Returns wall-clock time since clock instantiation
         double elapsedClockTime() const;
 
-        //- Returns wall-clock time from last call of clockTimeIncrement()
+        //- Returns wall-clock time since last clockTimeIncrement() call
         double clockTimeIncrement() const;
 };
 

src/OpenFOAM/global/clockTime/clockTime.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,11 +28,21 @@ Class
     Foam::clockTime
 
 Description
-    Starts timing (using rtc) and returns elapsed time from start.
+    Starts timing and returns elapsed time from start.
-    Better resolution (2uSec instead of ~20mSec) than cpuTime.
+    Uses std::chrono::high_resolution_clock for better resolution
+    (2uSec instead of ~20mSec) than cpuTime.
+
+Note
+    It has twice the storage requirement of a simple clockValue since
+    it tracks both total and incremental elapsed times.
+    Additionally, it always invokes a clock query on construction
+    which may make it less desirable for arrays of values (for example).
+
+See Also
+    Foam::clockValue
 
 SourceFiles
-    clockTime.C
+    clockTimeI.H
 
 \*---------------------------------------------------------------------------*/
 
@@ -54,37 +64,34 @@ class clockTime
 {
     // Private Data
 
-        //- The values being used.
+        //- Time point at start, or after resetTime
-        typedef clockValue value_type;
+        clockValue start_;
 
-        //- Start time, at the time of construction
+        //- Time point when elapsedTime or timeIncrement was called
-        value_type start_;
+        mutable clockValue last_;
-
-        //- Last time when elapsedTime or timeIncrement was called
-        mutable value_type last_;
 
 
 public:
 
     // Constructors
 
-        //- Construct with the current clock time for the starting value
+        //- Construct with the current clock value for the start point
-        clockTime();
+        inline clockTime();
 
-        //- Construct with the given clock value for the starting value
+        //- Implicit construct from the clock value as the start point
-        clockTime(const clockValue& clockval);
+        inline clockTime(const clockValue& clockval);
 
 
     // Member Functions
 
-        //- Reset to use the current time for the start time
+        //- Reset to use the current clock value for the start point
-        void resetTime();
+        inline void resetTime();
 
-        //- Return time (in seconds) from the start
+        //- The time [seconds] since the start point
-        double elapsedTime() const;
+        inline double elapsedTime() const;
 
-        //- Return time (in seconds) since last call to timeIncrement()
+        //- The time [seconds] since the last call to timeIncrement()
-        double timeIncrement() const;
+        inline double timeIncrement() const;
 };
 
 
@@ -94,6 +101,10 @@ public:
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
+#include "clockTimeI.H"
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
 #endif
 
 // ************************************************************************* //

src/OpenFOAM/global/clockTime/clockTimeI.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -25,18 +25,16 @@ License
 
 \*---------------------------------------------------------------------------*/
 
-#include "clockTime.H"
-
 // * * * * * * * * * * * * * * * * Constructors  * * * * * * * * * * * * * * //
 
-Foam::clockTime::clockTime()
+inline Foam::clockTime::clockTime()
 :
-    start_(true),
+    start_(true),  // == clockValue::now()
     last_(start_)
 {}
 
 
-Foam::clockTime::clockTime(const clockValue& clockval)
+inline Foam::clockTime::clockTime(const clockValue& clockval)
 :
     start_(clockval),
     last_(start_)
@@ -45,25 +43,25 @@ Foam::clockTime::clockTime(const clockValue& clockval)
 
 // * * * * * * * * * * * * * * * Member Functions  * * * * * * * * * * * * * //
 
-void Foam::clockTime::resetTime()
+inline void Foam::clockTime::resetTime()
 {
     last_.update();
     start_ = last_;
 }
 
 
-double Foam::clockTime::elapsedTime() const
+inline double Foam::clockTime::elapsedTime() const
 {
     last_.update();
-    return (last_ - start_);
+    return static_cast<double>(last_ - start_);
 }
 
 
-double Foam::clockTime::timeIncrement() const
+inline double Foam::clockTime::timeIncrement() const
 {
-    const value_type prev(last_);
+    const auto prev(last_);
     last_.update();
-    return (last_ - prev);
+    return static_cast<double>(last_ - prev);
 }
 
 

src/OpenFOAM/global/clockValue/clockValue.C

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018-2019 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -26,62 +26,11 @@ License
 \*---------------------------------------------------------------------------*/
 
 #include "clockValue.H"
-#include "IOstreams.H"
-
 #include <sstream>
 #include <iomanip>
 
-// * * * * * * * * * * * * * * * * Constructors  * * * * * * * * * * * * * * //
-
-Foam::clockValue::clockValue()
-:
-    value_(value_type::zero())
-{}
-
-
-Foam::clockValue::clockValue(const value_type& value)
-:
-    value_(value)
-{}
-
-
-Foam::clockValue::clockValue(bool useNow)
-:
-    value_(value_type::zero())
-{
-    if (useNow)
-    {
-        update();
-    }
-}
-
-
 // * * * * * * * * * * * * * * * Member Functions  * * * * * * * * * * * * * //
 
-void Foam::clockValue::clear()
-{
-    value_ = value_type::zero();
-}
-
-
-void Foam::clockValue::update()
-{
-    value_ = std::chrono::high_resolution_clock::now().time_since_epoch();
-}
-
-
-Foam::clockValue Foam::clockValue::elapsed() const
-{
-    return (now() -= *this);
-}
-
-
-long Foam::clockValue::seconds() const
-{
-    return std::chrono::duration_cast<std::chrono::seconds>(value_).count();
-}
-
-
 std::string Foam::clockValue::str() const
 {
     std::ostringstream os;
@@ -128,44 +77,4 @@ std::string Foam::clockValue::str() const
 }
 
 
-// * * * * * * * * * * * * * * * Member Operators  * * * * * * * * * * * * * //
-
-Foam::clockValue::operator double () const
-{
-    return
-    (
-        (double(value_.count()) * value_type::period::num)
-      / value_type::period::den
-    );
-}
-
-
-Foam::clockValue& Foam::clockValue::operator-=(const clockValue& rhs)
-{
-    value_ -= rhs.value_;
-    return *this;
-}
-
-
-Foam::clockValue& Foam::clockValue::operator+=(const clockValue& rhs)
-{
-    value_ += rhs.value_;
-    return *this;
-}
-
-
-// * * * * * * * * * * * * * * * Global Operators  * * * * * * * * * * * * * //
-
-Foam::clockValue Foam::operator-(const clockValue& a, const clockValue& b)
-{
-    return clockValue(a.value() - b.value());
-}
-
-
-Foam::clockValue Foam::operator+(const clockValue& a, const clockValue& b)
-{
-    return clockValue(a.value() + b.value());
-}
-
-
 // ************************************************************************* //

src/OpenFOAM/global/clockValue/clockValue.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018-2019 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,8 +28,10 @@ Class
 
 Description
     Access to high-resolution clock value with some basic operations.
+    Used to calculate time durations, elapsed times etc.
 
 SourceFiles
+    clockValueI.H
     clockValue.C
 
 \*---------------------------------------------------------------------------*/
@@ -51,11 +53,19 @@ namespace Foam
 
 class clockValue
 {
-    // Private Data
+public:
+
+    // Public Types
 
         //- Time structure used
         typedef std::chrono::high_resolution_clock::duration value_type;
 
+
+private:
+
+    // Private Data
+
+        //- The time start point or the time duration.
         value_type value_;
 
 
@@ -64,43 +74,44 @@ public:
     // Constructors
 
         //- Construct zero initialized
-        clockValue();
+        inline clockValue();
 
-        //- Construct from duration with the same clock base
+        //- Construct with current time.
-        explicit clockValue(const value_type& value);
+        //  The bool is for tagged dispatch only (its value is ignored).
+        inline explicit clockValue(bool);
 
-        //- Construct zero initialized or with current time
+        //- Copy construct from duration with the same clock base
-        explicit clockValue(bool useNow);
+        inline explicit clockValue(const value_type& value);
 
 
     // Factory Methods
 
-        //- Return the current time value from the system
+        //- The current clock value from the system
-        inline static clockValue now()
+        inline static clockValue now();
-        {
-            return clockValue(true);
-        }
 
 
     // Member Functions
 
-        //- Return the value
+        //- The time duration
         inline const value_type& value() const
         {
             return value_;
         }
 
         //- Reset to zero
-        void clear();
+        inline void clear();
 
         //- Update to the current now() time from the system
-        void update();
+        inline void update();
-
-        //- The time elapsed from now() since the start time.
-        clockValue elapsed() const;
 
         //- The value in seconds (rounded)
-        long seconds() const;
+        inline long seconds() const;
+
+        //- The time duration elapsed until now() since the start point
+        inline clockValue elapsed() const;
+
+        //- The time elapsed [seconds] until now() since the start point
+        inline double elapsedTime() const;
 
         //- Format as day-hh:mm:ss string
         std::string str() const;
@@ -109,23 +120,29 @@ public:
     // Operators
 
         //- Conversion operator to seconds in floating point
-        operator double() const;
+        inline operator double() const;
 
-        //- Subtract time value
+        //- Subtract clock value
-        clockValue& operator-=(const clockValue& rhs);
+        inline clockValue& operator-=(const clockValue& rhs);
 
-        //- Add time value
+        //- Add clock value
-        clockValue& operator+=(const clockValue& rhs);
+        inline clockValue& operator+=(const clockValue& rhs);
 };
 
 
 // Global Operators
 
 //- Subtraction of clock values
-clockValue operator-(const clockValue& a, const clockValue& b);
+inline clockValue operator-(const clockValue& a, const clockValue& b)
+{
+    return clockValue(a.value() - b.value());
+}
 
 //- Addition of clock values
-clockValue operator+(const clockValue& a, const clockValue& b);
+inline clockValue operator+(const clockValue& a, const clockValue& b)
+{
+    return clockValue(a.value() + b.value());
+}
 
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
@@ -134,6 +151,10 @@ clockValue operator+(const clockValue& a, const clockValue& b);
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
+#include "clockValueI.H"
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
 #endif
 
 // ************************************************************************* //

src/OpenFOAM/global/clockValue/clockValueI.H

@@ -0,0 +1,114 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | www.openfoam.com
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+    Copyright (C) 2020 OpenCFD Ltd.
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+    for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+\*---------------------------------------------------------------------------*/
+
+// * * * * * * * * * * * * * Static Member Functions * * * * * * * * * * * * //
+
+inline Foam::clockValue Foam::clockValue::now()
+{
+    return clockValue(true);
+}
+
+
+// * * * * * * * * * * * * * * * * Constructors  * * * * * * * * * * * * * * //
+
+inline Foam::clockValue::clockValue()
+:
+    value_(value_type::zero())
+{}
+
+
+inline Foam::clockValue::clockValue(bool)
+:
+    value_(std::chrono::high_resolution_clock::now().time_since_epoch())
+{}
+
+
+inline Foam::clockValue::clockValue(const value_type& value)
+:
+    value_(value)
+{}
+
+
+// * * * * * * * * * * * * * * * Member Functions  * * * * * * * * * * * * * //
+
+inline void Foam::clockValue::clear()
+{
+    value_ = value_type::zero();
+}
+
+
+inline void Foam::clockValue::update()
+{
+    value_ = std::chrono::high_resolution_clock::now().time_since_epoch();
+}
+
+
+inline long Foam::clockValue::seconds() const
+{
+    return std::chrono::duration_cast<std::chrono::seconds>(value_).count();
+}
+
+
+inline Foam::clockValue Foam::clockValue::elapsed() const
+{
+    return (clockValue::now() -= *this);
+}
+
+
+inline double Foam::clockValue::elapsedTime() const
+{
+    return static_cast<double>(this->elapsed());
+}
+
+
+// * * * * * * * * * * * * * * * Member Operators  * * * * * * * * * * * * * //
+
+inline Foam::clockValue::operator double() const
+{
+    return
+    (
+        (double(value_.count()) * value_type::period::num)
+      / value_type::period::den
+    );
+}
+
+
+inline Foam::clockValue& Foam::clockValue::operator-=(const clockValue& rhs)
+{
+    value_ -= rhs.value_;
+    return *this;
+}
+
+
+inline Foam::clockValue& Foam::clockValue::operator+=(const clockValue& rhs)
+{
+    value_ += rhs.value_;
+    return *this;
+}
+
+
+// ************************************************************************* //