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:
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:
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: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