Module ui.timeval

A simple module to module to compare and do arithmetic with time values.

Usage:

    local TimeVal = require("ui/timeval")
    
    local tv_start = TimeVal:now()
    -- Do some stuff.
    -- You can add and subtract `TimeVal` objects.
    local tv_duration = TimeVal:now() - tv_start
    -- And convert that object to various more human-readable formats, e.g.,
    print(string.format("Stuff took %.3fms", tv_duration:tomsecs()))
    

Functions

TimeVal:new (from_o) Creates a new TimeVal object.
TimeVal:realtime () Creates a new TimeVal object based on the current wall clock time.
TimeVal:monotonic () Creates a new TimeVal object based on the current value from the system's MONOTONIC clock source.
TimeVal:monotonic_coarse () Ditto, but w/ CLOCKMONOTONICCOARSE if it's available and has a 1ms resolution or better (uses CLOCK_MONOTONIC otherwise).
TimeVal:realtime_coarse () Ditto, but w/ CLOCKREALTIMECOARSE if it's available and has a 1ms resolution or better (uses CLOCK_REALTIME otherwise).
TimeVal:boottime () Ditto, but w/ CLOCK_BOOTTIME (will return a TimeVal set to 0, 0 if the clock source is unsupported, as it's 2.6.39+) Only use it if you know it's going to be supported, otherwise, prefer the four following aliases.
TimeVal:tonumber () Converts a TimeVal object to a Lua (decimal) number (sec.usecs) (accurate to the ms, rounded to 4 decimal places)
TimeVal:tousecs () Converts a TimeVal object to a Lua (int) number (resolution: 1µs)
TimeVal:tomsecs () Converts a TimeVal object to a Lua (int) number (resolution: 1ms).
TimeVal:fromnumber (seconds) Converts a Lua (decimal) number (sec.usecs) to a TimeVal object
TimeVal:getDuration (start_tv) Compare a past MONOTONIC TimeVal object to now, returning the elapsed time between the two.
TimeVal:getDurationUs (start_tv) Compare a past MONOTONIC TimeVal object to now, returning the elapsed time between the two.
TimeVal:getDurationMs (start_tv) Compare a past MONOTONIC TimeVal object to now, returning the elapsed time between the two.
TimeVal:isPositive () Checks if a TimeVal object is positive
TimeVal:isZero () Checks if a TimeVal object is zero

Tables

TimeVal TimeVal object.

Fields

TimeVal.now Alias for monotonic_coarse.
TimeVal.zero We often need a const TimeVal set to zero...
TimeVal.huge Ditto for one set to math.huge


Functions

TimeVal:new (from_o)
Creates a new TimeVal object.

Parameters:

  • from_o

Returns:

    TimeVal

Usage:

    local timev = TimeVal:new{
        sec = 10,
        usec = 10000,
    }
TimeVal:realtime ()
Creates a new TimeVal object based on the current wall clock time. (e.g., gettimeofday / clockgettime(CLOCKREALTIME).

This is a simple wrapper around util.gettime() to get all the niceties of a TimeVal object. If you don't need sub-second precision, prefer os.time(). Which means that, yes, this is a fancier POSIX Epoch ;).

Returns:

    TimeVal

Usage:

    local TimeVal = require("ui/timeval")
    local tv_start = TimeVal:realtime()
    -- Do some stuff.
    -- You can add and substract TimeVal objects.
    local tv_duration = TimeVal:realtime() - tv_start
TimeVal:monotonic ()
Creates a new TimeVal object based on the current value from the system's MONOTONIC clock source. (e.g., clockgettime(CLOCKMONOTONIC).)

POSIX guarantees that this clock source will never go backwards (but it may return the same value multiple times). On Linux, this will not account for time spent with the device in suspend (unlike CLOCK_BOOTTIME).

Returns:

    TimeVal
TimeVal:monotonic_coarse ()
Ditto, but w/ CLOCKMONOTONICCOARSE if it's available and has a 1ms resolution or better (uses CLOCK_MONOTONIC otherwise).
TimeVal:realtime_coarse ()
Ditto, but w/ CLOCKREALTIMECOARSE if it's available and has a 1ms resolution or better (uses CLOCK_REALTIME otherwise).
TimeVal:boottime ()
Ditto, but w/ CLOCK_BOOTTIME (will return a TimeVal set to 0, 0 if the clock source is unsupported, as it's 2.6.39+) Only use it if you know it's going to be supported, otherwise, prefer the four following aliases.
TimeVal:tonumber ()
Converts a TimeVal object to a Lua (decimal) number (sec.usecs) (accurate to the ms, rounded to 4 decimal places)
TimeVal:tousecs ()
Converts a TimeVal object to a Lua (int) number (resolution: 1µs)
TimeVal:tomsecs ()
Converts a TimeVal object to a Lua (int) number (resolution: 1ms).

(Mainly useful when computing a time lapse for benchmarking purposes).

TimeVal:fromnumber (seconds)
Converts a Lua (decimal) number (sec.usecs) to a TimeVal object

Parameters:

  • seconds
TimeVal:getDuration (start_tv)
Compare a past MONOTONIC TimeVal object to now, returning the elapsed time between the two. (sec.usecs variant)

Returns a Lua (decimal) number (sec.usecs) (accurate to the ms, rounded to 4 decimal places) (i.e., :tonumber())

Parameters:

  • start_tv
TimeVal:getDurationUs (start_tv)
Compare a past MONOTONIC TimeVal object to now, returning the elapsed time between the two. (µs variant)

Returns a Lua (int) number (resolution: 1µs) (i.e., :tousecs())

Parameters:

  • start_tv
TimeVal:getDurationMs (start_tv)
Compare a past MONOTONIC TimeVal object to now, returning the elapsed time between the two. (ms variant)

Returns a Lua (int) number (resolution: 1ms) (i.e., :tomsecs())

Parameters:

  • start_tv
TimeVal:isPositive ()
Checks if a TimeVal object is positive
TimeVal:isZero ()
Checks if a TimeVal object is zero

Tables

TimeVal
TimeVal object. Maps to a POSIX struct timeval ().

Fields:

  • sec int floored number of seconds
  • usec int number of microseconds past that second.

Fields

TimeVal.now
Alias for monotonic_coarse.

The assumption being anything that requires accurate timestamps expects a monotonic clock source. This is certainly true for KOReader's UI scheduling.

TimeVal.zero
We often need a const TimeVal set to zero... LuaJIT doesn't actually support const values (Lua 5.4+): Do NOT modify it.
TimeVal.huge
Ditto for one set to math.huge
generated by LDoc 1.4.6 Last updated 2022-10-31 22:30:30