Module clock

The clock module returns time values derived from the Posix / C CLOCK_GETTIME function or equivalent. Most functions in the module return a number of seconds; functions whose names end in "64" return a 64-bit number of nanoseconds.

Below is a list of all clock functions.

time() time64() realtime() realtime64()

The wall clock time. Derived from C function clock_gettime(CLOCK_REALTIME).

Returns

seconds or nanoseconds since epoch (1970-01-01 00:00:00), adjusted.

Return type

number or cdata (ctype<int64_t>)

Example:

 
-- This will print an approximate number of years since 1970.clock = require('clock')print(clock.time() / (365*24*60*60))

See also fiber.time64 and the standard Lua function os.clock.

monotonic() monotonic64()

The monotonic time. Derived from C function clock_gettime(CLOCK_MONOTONIC). Monotonic time is similar to wall clock time but is not affected by changes to or from daylight saving time, or by changes done by a user. This is the best function to use with benchmarks that need to calculate elapsed time.

Returns

seconds or nanoseconds since the last time that the computer was booted.

Return type

number or cdata (ctype<int64_t>)

Example:

 
-- This will print nanoseconds since the start.clock = require('clock')print(clock.monotonic64())

proc() proc64()

The processor time. Derived from C function clock_gettime(CLOCK_PROCESS_CPUTIME_ID). This is the best function to use with benchmarks that need to calculate how much time has been spent within a CPU.

Returns

seconds or nanoseconds since processor start.

Return type

number or cdata (ctype<int64_t>)

Example:

 
-- This will print nanoseconds in the CPU since the start.clock = require('clock')print(clock.proc64())

thread() thread64()

The thread time. Derived from C function clock_gettime(CLOCK_THREAD_CPUTIME_ID). This is the best function to use with benchmarks that need to calculate how much time has been spent within a thread within a CPU.

Returns

seconds or nanoseconds since the transaction processor thread started.

Return type

number or cdata (ctype<int64_t>)

Example:

 
-- This will print seconds in the thread since the start.clock = require('clock')print(clock.thread64())

The time that a function takes within a processor. This function uses clock.proc(), therefore it calculates elapsed CPU time. Therefore it is not useful for showing actual elapsed time.

Parameters:

• function (function) — function or function reference

• ... — whatever values are required by the function.

Returns

table. first element – seconds of CPU time, second element – whatever the function returns.

Example:

 
-- Benchmark a function which sleeps 10 seconds.-- NB: bench() will not calculate sleep time.-- So the returned value will be {a number less than 10, 88}.clock = require('clock')fiber = require('fiber')function f(param)  fiber.sleep(param)  return 88endclock.bench(f, 10)