AuroraRuntime/Include/Aurora/Time/Time.hpp

/***
    Copyright (C) 2021 J Reece Wilson (a/k/a "Reece"). All rights reserved.

    File: Time.hpp
    Date: 2021-6-10
    Author: Reece
***/
#pragma once

#include "_Time.hpp"

namespace Aurora::Time
{
    /**
        Converts milliseconds from the Aurora epoch to a civil timestamp structure
         similar to or of std::tm
    */
    AUKN_SYM tm ToCivilTime(AuInt64 time, bool bIsUTC = true);

    /**
        Converts civil time to milliseconds from the Aurora epoch
    */
    AUKN_SYM AuInt64  FromCivilTime(const tm &time, bool bIsUTC = true);


    /**
        Normalizes a civil data structure with respect to UTC, given the two input parameters 'in' civil and 'shiftFrom' timezone hint
    */
    AUKN_SYM tm NormalizeCivilTimezone(const tm &in, ETimezoneShift shiftFrom = ETimezoneShift::eUTC);

    /**
        Translates the Aurora epoch to the standard unix epoch
    */
    AUKN_SYM AuInt64 ConvertAuroraToUnixMS(AuInt64 in);

    /**
        Translates the Aurora epoch to the standard unix epoch
    */
    AUKN_SYM AuInt64 ConvertAuroraToUnixNS(AuInt64 in);

    /**
        Translates a standard unix epoch to the Aurora epoch
    */
    AUKN_SYM AuInt64 ConvertUnixToAuroraMS(AuInt64 in);

    /**
        Translates a standard unix epoch to the Aurora epoch
    */
    AUKN_SYM AuInt64 ConvertUnixToAuroraNS(AuInt64 in);

    /**
        Retrieves wall clock in milliseconds from the Aurora epoch
    */
    AUKN_SYM AuInt64 CurrentClockMS();

    /**
        Retrieves wall clock in nanoseconds from the Aurora epoch
    */
    AUKN_SYM AuInt64 CurrentClockNS();

    /**
     * @brief Steady clock in jiffies
     * @return 
    */
    AUKN_SYM AuUInt64 SteadyClock();

    /**
        Returns a steady system clock of SteadyClockJiffies() with an undefined epoch.

        These values should be used to drive thread primitives, IO time, and tick delta.
        On a modern plaform, these should be affected by the users' calendar or NTP. 
        On stinkier platforms, who cares if we can run mostly bug free with an assumed-sane wall-clock, right?
    */
    AUKN_SYM AuUInt64 SteadyClockMS();

    /**
     * @brief 
     * @return 
    */
    AUKN_SYM AuUInt64 SteadyClockNS();

    /**
        Retrieves the freqency of jiffies per second
    */
    AUKN_SYM AuUInt64 SteadyClockJiffies();

    /**
     * @brief frequency in jiffies per second
     * @return 
    */
    AUKN_SYM AuUInt64 ThreadClockJiffies();

    /**
     * @brief time spent in userspace and in the kernel under this thread [in jiffies]
     * @return
    */
    AUKN_SYM AuUInt64 ThreadClock();

    /**
     * @brief time spent in userspace and in the kernel under this thread [in nanoseconds]
     * @return 
    */
    AUKN_SYM AuUInt64 ThreadClockNS();

    /**
     * @brief time spent in userspace and in the kernel under this thread [in milliseconds]
     * @return
    */
    AUKN_SYM AuUInt64 ThreadClockMS();

    /**
     * @brief frequency in jiffies per second
     * @return
    */
    AUKN_SYM AuUInt64 ProcessClockJiffies();

    /**
     * @brief time spent in userspace and in the kernel under this process [in jiffies]
     * @return 
    */
    AUKN_SYM AuUInt64 ProcessClock();

    /**
     * @brief time spent in userspace and in the kernel under this process [in nanoseconds]
     * @return
    */
    AUKN_SYM AuUInt64 ProcessClockNS();

    /**
     * @brief time spent in userspace and in the kernel under this process [in milliseconds]
     * @return
    */
    AUKN_SYM AuUInt64 ProcessClockMS();

    // Advanced clocks: ////////////////////////

    /**
     * @brief 
     * @return 
    */
    AUKN_SYM AuUInt64 ThreadUserClock();

    /**
     * @brief 
     * @return 
    */
    AUKN_SYM AuUInt64 ThreadUserClockNS();

    /**
     * @brief 
     * @return 
    */
    AUKN_SYM AuUInt64 ThreadUserClockMS();

    /**
     * @brief frequency
     * @return 
    */
    AUKN_SYM AuUInt64 ThreadUserClockJiffies();

    /**
     * @brief 
     * @return 
    */
    AUKN_SYM AuUInt64 ProcessUserClock();
    
    /**
     * @brief 
     * @return 
    */
    AUKN_SYM AuUInt64 ProcessUserClockNS();
    
    /**
     * @brief 
     * @return 
    */
    AUKN_SYM AuUInt64 ProcessUserClockMS();

    /**
     * @brief frequency
     * @return
    */
    AUKN_SYM AuUInt64 ProcessUserClockJiffies();

    /**
     * @brief 
     * @return 
    */
    AUKN_SYM AuUInt64 ThreadKernelClock();

    /**
     * @brief 
     * @return 
    */
    AUKN_SYM AuUInt64 ThreadKernelClockNS();

    /**
     * @brief 
     * @return 
    */
    AUKN_SYM AuUInt64 ThreadKernelClockMS();

    /**
     * @brief 
     * @return 
    */
    AUKN_SYM AuUInt64 ThreadKernelClockJiffies();

    /**
     * @brief 
     * @return 
    */
    AUKN_SYM AuUInt64 ProcessKernelClock();

    /**
     * @brief 
     * @return 
    */
    AUKN_SYM AuUInt64 ProcessKernelClockNS();

    /**
     * @brief 
     * @return 
    */
    AUKN_SYM AuUInt64 ProcessKernelClockMS();

    /**
     * @brief frequency
     * @return
    */
    AUKN_SYM AuUInt64 ProcessKernelClockJiffies();

    ////////////////////////////////////////////

    /**
        Converts seconds from the Aurora epoch to time_t
    */
    AUKN_SYM time_t   SToCTime(AuInt64 time);

    /**
        Converts nanoseconds from the Aurora epoch to time_t
    */
    AUKN_SYM time_t   NSToCTime(AuInt64 time);

    /**
        Converts milliseconds from the Aurora epoch to time_t
    */
    AUKN_SYM time_t   MSToCTime(AuInt64 time);

    AUKN_SYM AuInt64  CTimeToMS(time_t time);

    /**
     * @brief 
     * @return 
    */
    AUKN_SYM AuSPtr<IClock> GetWallClock();
    
    /**
     * @brief 
     * @return 
    */
    AUKN_SYM AuSPtr<IClock> GetSteadyClock();

    /**
     * @brief kernel + userland cycles used
     * @return
    */
    AUKN_SYM AuSPtr<IClock> GetProcessClock();

    /**
     * @brief user time used
     * @return 
    */
    AUKN_SYM AuSPtr<IClock> GetProcessUserClock();

    /**
     * @brief kernel (if known) cycles used
     * @return 
    */
    AUKN_SYM AuSPtr<IClock> GetProcessKernelClock();

    /**
     * @brief kernel + userland cycles used
     * @return
    */
    AUKN_SYM AuSPtr<IClock> GetThreadClock();

    /**
     * @brief user time used
     * @return 
    */
    AUKN_SYM AuSPtr<IClock> GetThreadUserClock();
    
    /**
     * @brief kernel (if known) cycles used
     * @return 
    */
    AUKN_SYM AuSPtr<IClock> GetThreadKernelClock();

    /**
     * @brief 
     * @param clock 
     * @return 
    */
    AUKN_SYM AuSPtr<IClock> GetClockFromEnum(EClock clock);

    // TODO: Unix style of GetClockTimeNSByEnum/GetClockResNSByEnum?
    // 
    // Interfaces make sense for code that would like to deal with abstract clocks
    // Accessing a single by a single query-clock API makes sense for general purpose use (eg: GetWallTimeNS/CurrentClockNS, SteadyClockNS(), ...)
    // 
    // A potential GetClock[Time/Res][NS]ByEnum(EClock::...) feels too bloated, but it is a nice hybrid between the two use cases
}