Timestamp.h

Go to the documentation of this file.

/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */
 
#ifndef META_OCEAN_BASE_TIMESTAMP_H
#define META_OCEAN_BASE_TIMESTAMP_H
 
#include "ocean/base/Base.h"
#include "ocean/base/Lock.h"
 
#include <atomic>
#include <cfloat>
#include <limits>
 
#ifndef OCEAN_BASE_TIMESTAMP_BOOTTIME_AVAILABLE
    #if !defined(OCEAN_PLATFORM_BUILD_WINDOWS) && defined(CLOCK_BOOTTIME)
        #define OCEAN_BASE_TIMESTAMP_BOOTTIME_AVAILABLE
    #endif
#endif // OCEAN_BASE_TIMESTAMP_BOOTTIME_AVAILABLE
 
#ifndef OCEAN_BASE_TIMESTAMP_UPTIMERAW_AVAILABLE
    #if defined(OCEAN_PLATFORM_BUILD_APPLE) && defined(CLOCK_UPTIME_RAW)
        #define OCEAN_BASE_TIMESTAMP_UPTIMERAW_AVAILABLE
    #endif
#endif // OCEAN_BASE_TIMESTAMP_UPTIMERAW_AVAILABLE
 
#ifndef OCEAN_BASE_TIMESTAMP_VIRTUAL_COUNTER_REGISTER_AVAILABLE
    #if defined(OCEAN_PLATFORM_BUILD_ANDROID) && (defined(__arm__) || defined(__aarch64__))
        #define OCEAN_BASE_TIMESTAMP_VIRTUAL_COUNTER_REGISTER_AVAILABLE
    #endif
#endif // OCEAN_BASE_TIMESTAMP_VIRTUAL_COUNTER_REGISTER_AVAILABLE
 
#ifndef OCEAN_BASE_TIMESTAMP_CUSTOM_POSIX_AVAILABLE
    #if !defined(OCEAN_PLATFORM_BUILD_WINDOWS)
        #define OCEAN_BASE_TIMESTAMP_CUSTOM_POSIX_AVAILABLE
    #endif
#endif
 
namespace Ocean
{
 
// Forward declaration.
class Timestamp;
 
/**
 * Definition of a vector holding Timestamp objects.
 * @see Timestamp
 * @ingroup base
 */
using Timestamps = std::vector<Timestamp>;
 
/**
 * This class implements a timestamp.
 * The timestamp is specified by the number of seconds since 01.01.1970 00:00:00 in UTC time.<br>
 * Depending on the underlying hardware the accuracy (update rate) of the timestamps can vary.<br>
 * The timestamp class wraps a floating value with 64 bit precision.
 * @ingroup base
 */
class OCEAN_BASE_EXPORT Timestamp
{
    public:
 
        /// Definition of the number of milliseconds in one second.
        static constexpr int64_t millisecondsPerSecond_ = 1000;
 
        /// Definition of the number of microseconds in one second.
        static constexpr int64_t microsecondsPerSecond_ = millisecondsPerSecond_ * 1000;
 
        /// Definition of the number of nanoseconds in one second.
        static constexpr int64_t nanosecondsPerSecond_ = microsecondsPerSecond_ * 1000;
 
    public:
 
        /**
         * Creates a new timestamp with invalid time.
         */
        Timestamp() = default;
 
        /**
         * Creates a new timestamp.
         * @param toNow Determines whether the timestamp holds the seconds since 01.01.1970 00:00:00 in UTC time, otherwise the timestamp will be initialized as invalid
         */
        explicit Timestamp(const bool toNow);
 
        /**
         * Creates a new timestamp with a given value.
         * @param timestamp Timestamp value
         */
        inline explicit Timestamp(const double timestamp);
 
        /**
         * Sets the timestamp to the current time.
         * The timestamp holds the seconds since 01.01.1970 00:00:00 in UTC time.
         * @return Reference to this object
         */
        Timestamp& toNow();
 
        /**
         * Sets the timestamp to invalid.
         * @return Reference to this object
         */
        inline Timestamp& toInvalid();
 
        /**
         * Returns this timestamp in nanoseconds.
         * @return The timestamp in nanoseconds, with range (-infinity, infinity)
         */
        inline int64_t nanoseconds() const;
 
        /**
         * Returns whether a specified amount of time has passed since this timestamp.
         * This function returns 'thisTimestamp + seconds <= currentTimestamp'.
         * @param seconds The number of seconds defining the time to check, with range [0, infinity)
         * @param currentTimestamp The current timestamp to use for comparison
         * @return True, if the time has passed or if this timestamp is invalid
         */
        inline bool hasTimePassed(const double seconds, const Timestamp& currentTimestamp = Timestamp(true)) const;
 
        /**
         * Returns whether the timestamp holds a valid time.
         * @return True, if so
         */
        inline bool isValid() const;
 
        /**
         * Returns whether the timestamp holds an invalid time.
         * @return True, if so
         */
        inline bool isInvalid() const;
 
        /**
         * Assign a new value.
         * @param timestamp Value to assign
         * @return Reference to this timestamp
         */
        inline Timestamp& operator=(const double timestamp);
 
        /**
         * Adds two timestamps.
         * @param right The right timestamp
         * @return New timestamp
         */
        inline Timestamp operator+(const Timestamp& right) const;
 
        /**
         * Adds and assigns two timestamps.
         * @param right The right timestamp
         * @return Reference to this timestamp
         */
        inline Timestamp& operator+=(const Timestamp& right);
 
        /**
         * Adds seconds to this timestamps.
         * @param seconds The number of seconds to add, with range (-infinity, infinity)
         * @return New timestamp
         */
        inline Timestamp operator+(const double seconds) const;
 
        /**
         * Adds and assigns seconds to this timestamps.
         * @param seconds The number of seconds to add, with range (-infinity, infinity)
         * @return Reference to this timestamp
         */
        inline Timestamp& operator+=(const double seconds);
 
        /**
         * Subtracts two timestamps.
         * @param right The right timestamp
         * @return New timestamp
         */
        inline Timestamp operator-(const Timestamp& right) const;
 
        /**
         * Subtracts and assigns two timestamps.
         * @param right The right timestamp
         * @return Reference to this timestamp
         */
        inline Timestamp& operator-=(const Timestamp& right);
 
        /**
         * Subtracts seconds from this timestamp.
         * @param seconds The number of seconds to subtract, with range (-infinity, infinity)
         * @return New timestamp
         */
        inline Timestamp operator-(const double seconds) const;
 
        /**
         * Subtracts and assigns seconds from this timestamp.
         * @param seconds The number of seconds to subtract, with range (-infinity, infinity)
         * @return Reference to this timestamp
         */
        inline Timestamp& operator-=(const double seconds);
 
        /**
         * Returns whether the this timestamp is lesser than the right one.
         * @param right The right timestamp
         * @return True, if so
         */
        inline bool operator<(const Timestamp& right) const;
 
        /**
         * Returns whether the this timestamp is lesser or equal to the right one.
         * @param right The right timestamp
         * @return True, if so
         */
        inline bool operator<=(const Timestamp& right) const;
 
        /**
         * Returns whether the this timestamp is greater than the right one.
         * @param right The right timestamp
         * @return True, if so
         */
        inline bool operator>(const Timestamp& right) const;
 
        /**
         * Returns whether the this timestamp is greater or equal to the right one.
         * @param right The right timestamp
         * @return True, if so
         */
        inline bool operator>=(const Timestamp& right) const;
 
        /**
         * Returns whether two timestamps are identical.
         * @param right The right timestamp
         * @return True, if so
         */
        inline bool operator==(const Timestamp& right) const;
 
        /**
         * Returns whether two timestamps are not identical.
         * @param right The right timestamp
         * @return True, if so
         */
        inline bool operator!=(const Timestamp& right) const;
 
        /**
         * Cast operator for the timestamp value.
         * @return Timestamp
         */
        explicit inline operator double() const;
 
        /**
         * Hash function.
         * @param timestamp The timestamp for which the hash value will be determined
         * @return The resulting hash value
         */
        inline size_t operator()(const Timestamp& timestamp) const;
 
        /**
         * Converts seconds to milliseconds.
         * @param seconds The seconds to convert, with range (-infinity, infinity)
         * @return The resulting milliseconds
         */
        static constexpr int64_t seconds2milliseconds(const double seconds);
 
        /**
         * Converts seconds to microseconds.
         * @param seconds The seconds to convert, with range (-infinity, infinity)
         * @return The resulting microseconds
         */
        static constexpr int64_t seconds2microseconds(const double seconds);
 
        /**
         * Converts seconds to nanoseconds.
         * @param seconds The seconds to convert, with range (-infinity, infinity)
         * @return The resulting nanoseconds
         */
        static constexpr int64_t seconds2nanoseconds(const double seconds);
 
        /**
         * Converts milliseconds to seconds.
         * @param milliseconds The milliseconds to convert, with range (-infinity, infinity)
         * @return The resulting seconds
         */
        static constexpr double milliseconds2seconds(const int64_t milliseconds);
 
        /**
         * Converts microseconds to seconds.
         * @param microseconds The microseconds to convert, with range (-infinity, infinity)
         * @return The resulting seconds
         */
        static constexpr double microseconds2seconds(const int64_t microseconds);
 
        /**
         * Converts nanoseconds to seconds.
         * @param nanoseconds The nanoseconds to convert, with range (-infinity, infinity)
         * @return The resulting seconds
         */
        static constexpr double nanoseconds2seconds(const int64_t nanoseconds);
 
    protected:
 
        /**
         * Returns the of an invalid timestamp.
         * @return Invalid timestamp value
         */
        static constexpr double invalidTimestampValue();
 
    protected:
 
        /// Timestamp value.
        double value_ = invalidTimestampValue();
};
 
/**
 * This class is a helper class allowing to converter timestamps defined in a specific time domain to unix timestamps.
 */
class OCEAN_BASE_EXPORT TimestampConverter
{
    public:
 
        /**
         * Definition of individual time domains.
         */
        enum TimeDomain : uint32_t
        {
            /// An invalid time domain.
            TD_INVALID = 0u,
            /// The monotonically increasing time domain defined in nanoseconds, not increasing during system sleep.
            TD_MONOTONIC,
 
#ifdef OCEAN_BASE_TIMESTAMP_BOOTTIME_AVAILABLE
            /// The monotonically increasing time domain defined in nanoseconds, increasing during system sleep, not available on Windows.
            TD_BOOTTIME,
#endif
 
#ifdef OCEAN_BASE_TIMESTAMP_UPTIMERAW_AVAILABLE
            /// The monotonically increasing time domain defined in nanoseconds, the time the system has been awake since the last time it was restarted.
            TD_UPTIME_RAW,
#endif
 
#ifdef OCEAN_BASE_TIMESTAMP_VIRTUAL_COUNTER_REGISTER_AVAILABLE
            TD_VIRTUAL_COUNTER_REGISTER,
#endif
 
#ifdef OCEAN_BASE_TIMESTAMP_CUSTOM_POSIX_AVAILABLE
            /// A custom POSIX clock id specified by the user.
            TD_CUSTOM_POSIX
#endif
        };
 
        /**
         * Definition of an invalid value.
         */
        static constexpr int64_t invalidValue_ = std::numeric_limits<int64_t>::lowest();
 
    public:
 
        /**
         * Creates an invalid converter object.
         * @see isValid().
         */
        TimestampConverter() = default;
 
        /**
         * Default destructor.
         */
        ~TimestampConverter() = default;
 
        /**
         * Creates a new converter object for a specific time domain.
         * @param timeDomain The time domain for which the converter will be created
         * @param necessaryMeasurements The number of measurements necessary to determine the offset between the domain time and the unix time, with range [1, infinity)
         */
        explicit TimestampConverter(const TimeDomain timeDomain, const size_t necessaryMeasurements = 100);
 
#ifdef OCEAN_BASE_TIMESTAMP_CUSTOM_POSIX_AVAILABLE
 
        /**
         * Creates a new converter object for a custom POSIX clock id.
         * @param timeDomain The time domain for which the converter will be created, must be TD_CUSTOM_POSIX
         * @param customPosixClockId The custom POSIX clock id to use for time conversion
         * @param necessaryMeasurements The number of measurements necessary to determine the offset between the domain time and the unix time, with range [1, infinity)
         */
        explicit TimestampConverter(const TimeDomain timeDomain, const int customPosixClockId, const size_t necessaryMeasurements);
#endif
 
        /**
         * Move constructor.
         * @param converter The converter to be moved
         */
        inline TimestampConverter(TimestampConverter&& converter) noexcept;
 
        /**
         * Converts a timestamp defined in the converter's time domain to a unix timestamp.
         * @param domainTimestampNs The timestamp in the converter's time domain, in nanoseconds, with range (-infinity, infinity)
         * @return The converted unix timestamp
         */
        Timestamp toUnix(const int64_t domainTimestampNs);
 
        /**
         * Converts a timestamp defined in the converter's time domain to a unix timestamp.
         * @param domainTimestampSeconds The timestamp in the converter's time domain, in seconds, with range (-infinity, infinity)
         * @return The converted unix timestamp
         */
        Timestamp toUnix(const double domainTimestampSeconds);
 
        /**
         * Returns whether a given domain timestamp is within a specified range of the current domain timestamp.
         * @param domainTimestampNs The domain timestamp to check, in nanoseconds, with range (-infinity, infinity)
         * @param maxDistance The maximal distance between the domain timestamp and the current domain timestamp, in seconds, with range [0, infinity)
         * @param distance Optional resulting distance between the domain timestamp and the current domain timestamp, in seconds, with range (-infinity, infinity)
         * @return True, if so
         */
        bool isWithinRange(const int64_t domainTimestampNs, const double maxDistance = 1.0, double* distance = nullptr);
 
        /**
         * Returns the current timestamp in the time domain of this converter.
         * @return The current timestamp in the converter's time domain, in nanoseconds, invalidValue_ in case of an error
         */
        int64_t currentDomainTimestampNs() const;
 
        /**
         * Returns the time domain of this converter.
         * @return The converter's time domain
         */
        inline TimeDomain timeDomain() const;
 
        /**
         * Returns the offset between the domain time and the unix time, in nanoseconds.
         * Unix time = domain time + domainToUnixOffset
         * @return The offset between the domain time and the unix time, in nanoseconds, with range (-infinity, infinity)
         */
        int64_t domainToUnixOffset();
 
        /**
         * Returns the number of measurements.
         * @return The converter's number of measurements
         */
        inline size_t measurements() const;
 
        /**
         * Returns whether this converter has been initialized with a valid time domain.
         * @return True, if so
         */
        inline bool isValid() const;
 
        /**
         * Returns whether this converter is valid.
         * @return True, if so
         */
        inline operator bool() const;
 
        /**
         * Move operator.
         * @param converter The converter to be moved
         * @return Reference to this object
         */
        TimestampConverter& operator=(TimestampConverter&& converter) noexcept;
 
        /**
         * Returns the current timestamp in a specified time domain.
         * @param timeDomain The time domain for which the current timestamp will be returned
         * @return The current timestamp in the specified time domain, in nanoseconds
         */
        static int64_t currentDomainTimestampNs(const TimeDomain timeDomain);
 
        /**
         * Converts a timestamp which is defined in seconds to a timestamp which is defined in nanoseconds.
         * The timestamp is defined by (timeValue / timeDenominator) * 1s.<br>
         * The resulting timestamp will be (newTimeValue / 1000000000) * 1s.
         * @param timeValue The time value, in seconds, with range (-infinity, infinity)
         * @param timeDenominator The denominator corresponding to the time value (sometimes call time scale), with range [1, infinity)
         * @return The resulting timestamp in nanoseconds, with range (-infinity, infinity)
         */
        static int64_t timestampInNs(const int64_t timeValue, const int64_t timeDenominator);
 
#ifndef OCEAN_PLATFORM_BUILD_WINDOWS
 
        /**
         * Return the current timestamp in a specified POSIX clock id.
         * @param posixClockId The POSIX clock id for which the current timestamp will be returned
         * @return The current timestamp in the specified POSIX clock id, in nanoseconds
         */
        static int64_t currentTimestampNs(const int posixClockId);
 
    protected:
 
        /**
         * Returns the POSIX clock id associated with a time domain.
         * @param timeDomain The time domain for which the associated POSIX clock id will be returned
         * @return The POSIX clock id associated with the specified time domain, -1 if no associated POSIX clock id exists
         */
        static int posixClockId(const TimeDomain timeDomain);
 
#endif // OCEAN_PLATFORM_BUILD_WINDOWS
 
    protected:
 
        /// The time domain of this converter.
        TimeDomain timeDomain_ = TD_INVALID;
 
        /// The offset between the domain time and the unix time, in nanoseconds.
        std::atomic_int64_t domainToUnixOffsetNs_ = invalidValue_;
 
        /// The initial domain timestamp, in nanoseconds.
        int64_t initialDomainNs_ = invalidValue_;
 
        /// The initial unix timestamp, in nanoseconds.
        int64_t initialUnixNs_ = invalidValue_;
 
        /// The measured sum of the domain to unix offsets, in nanoseconds.
        int64_t sumDomainToUnixOffsetNs_ = 0;
 
        /// The number of measurements.
        size_t measurements_ = 0;
 
        /// The number of necessary measurements before the converter keeps the determined offset fixed.
        size_t necessaryMeasurements_ = 0;
 
        /// The optional frequency of the domain time, in Hz (in case the domain time is not defined in nanoseconds).
        uint64_t domainFrequency_ = 0ull;
 
        /// The converter's lock.
        mutable Lock lock_;
 
#ifndef OCEAN_PLATFORM_BUILD_WINDOWS
        /// The POSIX clock id associated with the time domain.
        int domainPosixClockId_ = -1;
#endif
};
 
inline Timestamp::Timestamp(const double timestamp) :
    value_(timestamp)
{
    // nothing to do here
}
 
inline Timestamp& Timestamp::toInvalid()
{
    value_ = invalidTimestampValue();
 
    return *this;
}
 
inline int64_t Timestamp::nanoseconds() const
{
    ocean_assert(isValid());
 
    return seconds2nanoseconds(value_);
}
 
inline bool Timestamp::hasTimePassed(const double seconds, const Timestamp& currentTimestamp) const
{
    ocean_assert(seconds >= 0.0);
    ocean_assert(currentTimestamp.isValid());
 
    if (!isValid())
    {
        return true;
    }
 
    return double(*this) + seconds <= double(currentTimestamp);
}
 
inline bool Timestamp::isValid() const
{
    return value_ != invalidTimestampValue();
}
 
inline bool Timestamp::isInvalid() const
{
    return value_ == invalidTimestampValue();
}
 
inline Timestamp& Timestamp::operator=(const double timestamp)
{
    value_ = timestamp;
 
    return *this;
}
 
inline Timestamp Timestamp::operator+(const Timestamp& right) const
{
    return Timestamp(value_ + right.value_);
}
 
inline Timestamp& Timestamp::operator+=(const Timestamp& right)
{
    value_ += right.value_;
 
    return *this;
}
 
inline Timestamp Timestamp::operator+(const double seconds) const
{
    return Timestamp(value_ + seconds);
}
 
inline Timestamp& Timestamp::operator+=(const double seconds)
{
    value_ += seconds;
 
    return *this;
}
 
inline Timestamp Timestamp::operator-(const Timestamp& right) const
{
    return Timestamp(value_ - right.value_);
}
 
inline Timestamp& Timestamp::operator-=(const Timestamp& right)
{
    value_ -= right.value_;
 
    return *this;
}
 
inline Timestamp Timestamp::operator-(const double seconds) const
{
    return Timestamp(value_ - seconds);
}
 
inline Timestamp& Timestamp::operator-=(const double seconds)
{
    value_ -= seconds;
 
    return *this;
}
 
inline bool Timestamp::operator<(const Timestamp& right) const
{
    return value_ < right.value_;
}
 
inline bool Timestamp::operator<=(const Timestamp& right) const
{
    return value_ <= right.value_;
}
 
inline bool Timestamp::operator>(const Timestamp& right) const
{
    return value_ > right.value_;
}
 
inline bool Timestamp::operator>=(const Timestamp& right) const
{
    return value_ >= right.value_;
}
 
inline bool Timestamp::operator==(const Timestamp& right) const
{
    return value_ == right.value_;
}
 
inline bool Timestamp::operator!=(const Timestamp& right) const
{
    return value_ != right.value_;
}
 
inline Timestamp::operator double() const
{
    return value_;
}
 
inline size_t Timestamp::operator()(const Timestamp& timestamp) const
{
    return std::hash<double>{}(double(timestamp));
}
 
constexpr int64_t Timestamp::seconds2milliseconds(const double seconds)
{
    // 1000 milliseconds  =  1 second
 
    if (seconds >= 0.0)
    {
        return int64_t(seconds * double(millisecondsPerSecond_) + 0.5);
    }
    else
    {
        return int64_t(seconds * double(millisecondsPerSecond_) - 0.5);
    }
}
 
constexpr int64_t Timestamp::seconds2microseconds(const double seconds)
{
    // 1000 milliseconds  =  1 second
    // 1000 microseconds  =  1 milliseconds
 
    if (seconds >= 0.0)
    {
        return int64_t(seconds * double(microsecondsPerSecond_) + 0.5);
    }
    else
    {
        return int64_t(seconds * double(microsecondsPerSecond_) - 0.5);
    }
}
 
constexpr int64_t Timestamp::seconds2nanoseconds(const double seconds)
{
    // 1000 milliseconds  =  1 second
    // 1000 microseconds  =  1 milliseconds
    // 1000 nanoseconds   =  1 microseconds
 
    if (seconds >= 0.0)
    {
        return int64_t(seconds * double(nanosecondsPerSecond_) + 0.5);
    }
    else
    {
        return int64_t(seconds * double(nanosecondsPerSecond_) - 0.5);
    }
}
 
constexpr double Timestamp::milliseconds2seconds(const int64_t milliseconds)
{
    return double(milliseconds) / double(millisecondsPerSecond_);
}
 
constexpr double Timestamp::microseconds2seconds(const int64_t microseconds)
{
    return double(microseconds) / double(microsecondsPerSecond_);
}
 
constexpr double Timestamp::nanoseconds2seconds(const int64_t nanoseconds)
{
    return double(nanoseconds) / double(nanosecondsPerSecond_);
}
 
constexpr double Timestamp::invalidTimestampValue()
{
    return -DBL_MAX;
}
 
inline TimestampConverter::TimestampConverter(TimestampConverter&& converter) noexcept
{
    *this = std::move(converter);
}
 
inline TimestampConverter::TimeDomain TimestampConverter::timeDomain() const
{
    return timeDomain_;
}
 
inline size_t TimestampConverter::measurements() const
{
    const ScopedLock scopedLock(lock_);
 
    return measurements_;
}
 
inline bool TimestampConverter::isValid() const
{
    return timeDomain_ != TD_INVALID && necessaryMeasurements_ != 0;
}
 
inline TimestampConverter::operator bool() const
{
    return isValid();
}
 
}
 
#endif // META_OCEAN_BASE_TIMESTAMP_H