Timing.h

Go to the documentation of this file.

#ifndef SimTK_SimTKCOMMON_TIMING_H_
#define SimTK_SimTKCOMMON_TIMING_H_

/* -------------------------------------------------------------------------- *
 *                       Simbody(tm): SimTKcommon                             *
 * -------------------------------------------------------------------------- *
 * This is part of the SimTK biosimulation toolkit originating from           *
 * Simbios, the NIH National Center for Physics-Based Simulation of           *
 * Biological Structures at Stanford, funded under the NIH Roadmap for        *
 * Medical Research, grant U54 GM072970. See https://simtk.org/home/simbody.  *
 *                                                                            *
 * Portions copyright (c) 2010-12 Stanford University and the Authors.        *
 * Authors: Michael Sherman                                                   *
 * Contributors:                                                              *
 *                                                                            *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may    *
 * not use this file except in compliance with the License. You may obtain a  *
 * copy of the License at http://www.apache.org/licenses/LICENSE-2.0.         *
 *                                                                            *
 * Unless required by applicable law or agreed to in writing, software        *
 * distributed under the License is distributed on an "AS IS" BASIS,          *
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.   *
 * See the License for the specific language governing permissions and        *
 * limitations under the License.                                             *
 * -------------------------------------------------------------------------- */

#include "SimTKcommon/internal/common.h"
#include "SimTKcommon/Constants.h"

// This header is needed on Mac and Linux for some or all of the Posix time 
// functions and the timespec struct. We include it on Windows also for 
// uniform cross-platform behavior, since there are many other useful time-
// date-handling symbols declared here on all platforms.
#include <ctime>


// macOS (OSX) 10.12 introduced support for clock_gettime().
// The following logic is based on documentation in /usr/local/Availability.h
// and from this site:
// https://developer.apple.com/library/content/documentation/DeveloperTools/Conceptual/cross_development/Using/using.html.
// This website also recommends using Availability.h over the similarly-helpful
// AvailabilityMacros.h.
#if defined(__APPLE__)
    #include <Availability.h>
#endif
// We'll use the following macros throughout Timing.(h|cpp).
// "MAX_ALLOWED" is the version of the OSX SDK used when building.
// "MIN_REQUIRED" is the "DEPLOYMENT_TARGET": earliest version on which the
//                binaries should run.
// One can use the 10.12 SDK to deploy to earlier releases, like 10.11. The SDK
// version determines if we need to declare clock_gettime() (e.g., developer is
// using an SDK older than 10.12), and the deployment target determines if we
// cannot expect the user's system to contain an implementation of
// clock_gettime() (e.g., user may be running an on OS older than 10.12).
// We need both of these macros because developers may only have the 10.12 SDK,
// but may want to use it to deploy to machines running 10.11. In such a case,
// we cannot declare clock_gettime() ourselves (the SDK does it), but we must
// still define it.
// The number 101200 identifies macOS version 10.12. The explicit version
// number must be used instead of a macro like __MAC_10_12 because pre-10.12
// systems won't have __MAC_10_12 defined.
#if defined(__APPLE__) && __MAC_OS_X_VERSION_MAX_ALLOWED < 101200
    // SDK is older than 10.12.
    #define SimTK_IS_APPLE_AND_MUST_DECLARE_CLOCK_GETTIME 1
#else
    #define SimTK_IS_APPLE_AND_MUST_DECLARE_CLOCK_GETTIME 0
#endif

#if defined(__APPLE__) && __MAC_OS_X_VERSION_MIN_REQUIRED < 101200
    // user's OS may be pre-10.12.
    #define SimTK_IS_APPLE_AND_MUST_DEFINE_CLOCK_GETTIME 1
#else
    #define SimTK_IS_APPLE_AND_MUST_DEFINE_CLOCK_GETTIME 0
#endif



#if defined(_MSC_VER)
    /* Posix nanosleep() sleeps the indicated number of nanoseconds and returns
    0, or if it is interrupted early it returns how much time was left in 
    rem and returns EINTR. Ours is not interruptable so will always succeed and
    return rem==0. It is OK if rem is NULL, but req==NULL or req<0 returns 
    EINVAL. A time of req==0 is allowed and our interpretation is that the 
    thread relinquishes its time slice to another ready-to-run thread if there
    is one, otherwise returns immediately. This implementation rounds the 
    desired sleep time to the nearest millisecond. On a Linux system, this 
    requires including <time.h> (or <ctime>), which we already included 
    above. */
    SimTK_SimTKCOMMON_EXPORT int nanosleep(const struct timespec* req, struct timespec* rem);

    /* Posix declares this handy function obsolete, but I don't think it is in
    any danger of going away. It sleeps for the given number of microseconds.
    However, using SimTK::sleepInNs() or SimTK::sleepInSec() is safer. */
    typedef unsigned int useconds_t;
    inline int usleep(useconds_t us) {
        struct timespec req;
        req.tv_sec  = (long) (us / 1000000U);
        req.tv_nsec = (long)((us % 1000000U)*1000U);
        int status = nanosleep(&req,0);
        return status ? -1 : 0;
    }
#endif

#if defined(_MSC_VER) || SimTK_IS_APPLE_AND_MUST_DECLARE_CLOCK_GETTIME
    // On Windows and OSX < 10.12, the Posix clock_gettime function is missing.
    typedef long clockid_t;

    /* These constants are the clock ids we support. All the varieties of 
    CLOCK_MONOTONIC are high resolution with no NTP adjustments. I measured 
    the resolutions on a single Windows 7 machine; hopefully they are typical
    (resolution here means how often they are updated):
      - MONOTONIC (counter):    0.001ms      1us
      - REALTIME (time of day):    1ms    1000us
      - CPUTIME (either):         20ms   20000us
    These are slightly conservative resolutions so you should be able to 
    achieve them in practice. */
    #define CLOCK_REALTIME           1 // time of day clock, from 1/1/1970
    #define CLOCK_MONOTONIC          2 // counter from last boot time
    #define CLOCK_MONOTONIC_HR       3 // "high resolution" (same)
    #define CLOCK_MONOTONIC_RAW      4 // "not subject to NTP adjustments" (same)
    #define CLOCK_THREAD_CPUTIME_ID  5 // current thread's cpu time (kernel+user)
    #define CLOCK_PROCESS_CPUTIME_ID 6 // cumulative cpu time of all threads of
                                       //   this process, live or dead

    /* Returns zero if it succeeds (or if tp==NULL); otherwise EINVAL. On a 
    Linux system, this requires including <time.h> (or <ctime>) and linking 
    with -lrt to get the realtime library. */
    SimTK_SimTKCOMMON_EXPORT int clock_gettime(clockid_t clock_id, 
                                               struct timespec *tp); 
#endif



namespace SimTK {

inline long long timespecToNs(const timespec& ts)
{   return (long long)ts.tv_sec*1000000000LL + (long long)ts.tv_nsec; }

inline void nsToTimespec(const long long& ns, timespec& ts) 
{   ts.tv_sec  = (long)(ns / 1000000000LL); // signed
    if (ns >= 0) ts.tv_nsec =  (long)(  ns  % 1000000000LL);
    else         ts.tv_nsec = -(long)((-ns) % 1000000000LL); }

inline double nsToSec(const long long& ns) 
{   return (double)(ns*SimTK_NS_TO_S); }

inline long long secToNs(const double& s) 
{   return (long long)(s*SimTK_S_TO_NS); }
inline double cpuTime() 
{   timespec ts;
    clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &ts);
    return (double)(timespecToNs(ts)*SimTK_NS_TO_S); }

inline double threadCpuTime() 
{   timespec ts;
    clock_gettime(CLOCK_THREAD_CPUTIME_ID, &ts);
    return (double)(timespecToNs(ts)*SimTK_NS_TO_S); }
inline long long realTimeInNs() {
    timespec ts;
    #ifdef CLOCK_MONOTONIC_RAW
        clock_gettime(CLOCK_MONOTONIC_RAW, &ts);
    #else
        clock_gettime(CLOCK_MONOTONIC, &ts);
    #endif
    return timespecToNs(ts);
}

inline double realTime() {return nsToSec(realTimeInNs());}

inline void sleepInNs(const long long& ns) 
{   timespec ts;
    nsToTimespec(ns, ts);
    nanosleep(&ts, 0); }

inline void sleepInSec(const double& seconds) {sleepInNs(secToNs(seconds));}
} // namespace SimTK

#endif // SimTK_SimTKCOMMON_TIMING_H_