[mypyc] Add experimental librt.time module with time() (#20723)

I've seen many performance-critical functions that have calls to
`time.time()`, which is perhaps not that surprising. I don't want to
just add a primitive for `time.time()`, since it's often monkey patched,
and primitive functions generally can't be monkey patched. Instead, I
add the `librt.time` module here, which has an efficient `time()`
function that can be used in performance-critical code (but it can't be
monkey patched).

In a microbenchmark this was up to 70% faster than using `time.time()`.

I used a lot of coding agent assist. I'm relying on CI to test the
Windows implementation.

Author: JukkaL

mypy/typeshed/stubs/librt/librt/time.pyi

@@ -0,0 +1 @@
+def time() -> float: ...

mypyc/build.py

@@ -120,6 +120,7 @@ class ModDesc(NamedTuple):
         ["vecs/librt_vecs.h", "vecs/vec_template.c"],
         ["vecs"],
     ),
+    ModDesc("librt.time", ["time/librt_time.c"], ["time/librt_time.h"], []),
 ]
 
 try:

mypyc/codegen/emitmodule.py

@@ -56,7 +56,7 @@
     short_id_from_name,
 )
 from mypyc.errors import Errors
-from mypyc.ir.deps import LIBRT_BASE64, LIBRT_STRINGS, SourceDep
+from mypyc.ir.deps import LIBRT_BASE64, LIBRT_STRINGS, LIBRT_TIME, SourceDep
 from mypyc.ir.func_ir import FuncIR
 from mypyc.ir.module_ir import ModuleIR, ModuleIRs, deserialize_modules
 from mypyc.ir.ops import DeserMaps, LoadLiteral
@@ -632,6 +632,8 @@ def generate_c_for_modules(self) -> list[tuple[str, str]]:
             ext_declarations.emit_line("#include <base64/librt_base64.h>")
         if any(LIBRT_STRINGS in mod.dependencies for mod in self.modules.values()):
             ext_declarations.emit_line("#include <strings/librt_strings.h>")
+        if any(LIBRT_TIME in mod.dependencies for mod in self.modules.values()):
+            ext_declarations.emit_line("#include <time/librt_time.h>")
         # Include headers for conditional source files
         source_deps = collect_source_dependencies(self.modules)
         for source_dep in sorted(source_deps, key=lambda d: d.path):
@@ -1102,6 +1104,10 @@ def emit_module_exec_func(
             emitter.emit_line("if (import_librt_strings() < 0) {")
             emitter.emit_line("return -1;")
             emitter.emit_line("}")
+        if LIBRT_TIME in module.dependencies:
+            emitter.emit_line("if (import_librt_time() < 0) {")
+            emitter.emit_line("return -1;")
+            emitter.emit_line("}")
         emitter.emit_line("PyObject* modname = NULL;")
         if self.multi_phase_init:
             emitter.emit_line(f"{module_static} = module;")

mypyc/ir/deps.py

@@ -49,6 +49,7 @@ def get_header(self) -> str:
 LIBRT_STRINGS: Final = Capsule("librt.strings")
 LIBRT_BASE64: Final = Capsule("librt.base64")
 LIBRT_VECS: Final = Capsule("librt.vecs")
+LIBRT_TIME: Final = Capsule("librt.time")
 
 BYTES_EXTRA_OPS: Final = SourceDep("bytes_extra_ops.c")
 BYTES_WRITER_EXTRA_OPS: Final = SourceDep("byteswriter_extra_ops.c")

mypyc/lib-rt/setup.py

@@ -148,5 +148,8 @@ def run(self) -> None:
                 include_dirs=[".", "vecs"],
                 extra_compile_args=cflags,
             ),
+            Extension(
+                "librt.time", ["time/librt_time.c"], include_dirs=["."], extra_compile_args=cflags
+            ),
         ]
     )

mypyc/lib-rt/time/librt_time.c

@@ -0,0 +1,140 @@
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+#include <time.h>
+#include <stdint.h>
+#include "librt_time.h"
+#include "pythoncapi_compat.h"
+#include "mypyc_util.h"
+
+#ifdef _WIN32
+#include <windows.h>
+#else
+#include <sys/time.h>
+#endif
+
+#ifdef MYPYC_EXPERIMENTAL
+
+// Internal function that returns a C double for mypyc primitives
+// Returns high-precision time in seconds (like time.time())
+static double
+time_time_internal(void) {
+#ifdef _WIN32
+    // Windows: Use GetSystemTimePreciseAsFileTime for ~100ns precision
+    FILETIME ft;
+    ULARGE_INTEGER large;
+
+    GetSystemTimePreciseAsFileTime(&ft);
+    large.LowPart = ft.dwLowDateTime;
+    large.HighPart = ft.dwHighDateTime;
+
+    // Windows FILETIME is 100-nanosecond intervals since January 1, 1601
+    // 116444736000000000 = number of 100-ns intervals between 1601 and 1970
+    // Convert directly to seconds: 100ns * 1e-9 = 1e-7
+    int64_t intervals = large.QuadPart - 116444736000000000LL;
+    return (double)intervals * 1e-7;
+
+#else  // Unix-like systems (Linux, macOS, BSD, etc.)
+
+    // Try clock_gettime(CLOCK_REALTIME) for nanosecond precision
+    // This is available on POSIX.1-2001 and later (widely available on modern systems)
+#if defined(_POSIX_TIMERS) && _POSIX_TIMERS > 0
+    struct timespec ts;
+    if (clock_gettime(CLOCK_REALTIME, &ts) == 0) {
+        // Convert seconds and nanoseconds separately to avoid large integer operations
+        return (double)ts.tv_sec + (double)ts.tv_nsec * 1e-9;
+    }
+    // Fall through to gettimeofday if clock_gettime failed
+#endif
+
+    // Fallback: gettimeofday for microsecond precision
+    // This is widely available (POSIX.1-2001, BSD, etc.)
+    struct timeval tv;
+    if (unlikely(gettimeofday(&tv, NULL) != 0)) {
+        PyErr_SetFromErrno(PyExc_OSError);
+        return CPY_FLOAT_ERROR;
+    }
+
+    // Convert seconds and microseconds separately to avoid large integer operations
+    return (double)tv.tv_sec + (double)tv.tv_usec * 1e-6;
+#endif
+}
+
+// Wrapper function for normal Python extension usage
+static PyObject*
+time_time(PyObject *self, PyObject *const *args, size_t nargs) {
+    if (nargs != 0) {
+        PyErr_SetString(PyExc_TypeError, "time() takes no arguments");
+        return NULL;
+    }
+
+    double result = time_time_internal();
+    if (result == CPY_FLOAT_ERROR) {
+        return NULL;
+    }
+    return PyFloat_FromDouble(result);
+}
+
+#endif
+
+static PyMethodDef librt_time_module_methods[] = {
+#ifdef MYPYC_EXPERIMENTAL
+    {"time", (PyCFunction)time_time, METH_FASTCALL,
+     PyDoc_STR("Return the current time in seconds since the Unix epoch as a floating point number.")},
+#endif
+    {NULL, NULL, 0, NULL}
+};
+
+#ifdef MYPYC_EXPERIMENTAL
+
+static int
+time_abi_version(void) {
+    return LIBRT_TIME_ABI_VERSION;
+}
+
+static int
+time_api_version(void) {
+    return LIBRT_TIME_API_VERSION;
+}
+
+#endif
+
+static int
+librt_time_module_exec(PyObject *m)
+{
+#ifdef MYPYC_EXPERIMENTAL
+    // Export mypyc internal C API via capsule
+    static void *time_api[LIBRT_TIME_API_LEN] = {
+        (void *)time_abi_version,
+        (void *)time_api_version,
+        (void *)time_time_internal,
+    };
+    PyObject *c_api_object = PyCapsule_New((void *)time_api, "librt.time._C_API", NULL);
+    if (PyModule_Add(m, "_C_API", c_api_object) < 0) {
+        return -1;
+    }
+#endif
+    return 0;
+}
+
+static PyModuleDef_Slot librt_time_module_slots[] = {
+    {Py_mod_exec, librt_time_module_exec},
+#ifdef Py_MOD_GIL_NOT_USED
+    {Py_mod_gil, Py_MOD_GIL_NOT_USED},
+#endif
+    {0, NULL}
+};
+
+static PyModuleDef librt_time_module = {
+    .m_base = PyModuleDef_HEAD_INIT,
+    .m_name = "time",
+    .m_doc = "Fast time() function optimized for mypyc",
+    .m_size = 0,
+    .m_methods = librt_time_module_methods,
+    .m_slots = librt_time_module_slots,
+};
+
+PyMODINIT_FUNC
+PyInit_time(void)
+{
+    return PyModuleDef_Init(&librt_time_module);
+}

mypyc/lib-rt/time/librt_time.h

@@ -0,0 +1,62 @@
+#ifndef LIBRT_TIME_H
+#define LIBRT_TIME_H
+
+#ifndef MYPYC_EXPERIMENTAL
+
+static int
+import_librt_time(void)
+{
+    // All librt.time features are experimental for now, so don't set up the API here
+    return 0;
+}
+
+#else  // MYPYC_EXPERIMENTAL
+
+#include <Python.h>
+
+#define LIBRT_TIME_ABI_VERSION 1
+#define LIBRT_TIME_API_VERSION 1
+#define LIBRT_TIME_API_LEN 3
+
+static void *LibRTTime_API[LIBRT_TIME_API_LEN];
+
+#define LibRTTime_ABIVersion (*(int (*)(void)) LibRTTime_API[0])
+#define LibRTTime_APIVersion (*(int (*)(void)) LibRTTime_API[1])
+#define LibRTTime_time (*(double (*)(void)) LibRTTime_API[2])
+
+static int
+import_librt_time(void)
+{
+    PyObject *mod = PyImport_ImportModule("librt.time");
+    if (mod == NULL)
+        return -1;
+    Py_DECREF(mod);  // we import just for the side effect of making the below work.
+    void *capsule = PyCapsule_Import("librt.time._C_API", 0);
+    if (capsule == NULL)
+        return -1;
+    memcpy(LibRTTime_API, capsule, sizeof(LibRTTime_API));
+    if (LibRTTime_ABIVersion() != LIBRT_TIME_ABI_VERSION) {
+        char err[128];
+        snprintf(err, sizeof(err), "ABI version conflict for librt.time, expected %d, found %d",
+            LIBRT_TIME_ABI_VERSION,
+            LibRTTime_ABIVersion()
+        );
+        PyErr_SetString(PyExc_ValueError, err);
+        return -1;
+    }
+    if (LibRTTime_APIVersion() < LIBRT_TIME_API_VERSION) {
+        char err[128];
+        snprintf(err, sizeof(err),
+                 "API version conflict for librt.time, expected %d or newer, found %d (hint: upgrade librt)",
+            LIBRT_TIME_API_VERSION,
+            LibRTTime_APIVersion()
+        );
+        PyErr_SetString(PyExc_ValueError, err);
+        return -1;
+    }
+    return 0;
+}
+
+#endif  // MYPYC_EXPERIMENTAL
+
+#endif  // LIBRT_TIME_H

mypyc/primitives/librt_time_ops.py

@@ -0,0 +1,14 @@
+from mypyc.ir.deps import LIBRT_TIME
+from mypyc.ir.ops import ERR_MAGIC_OVERLAPPING
+from mypyc.ir.rtypes import float_rprimitive
+from mypyc.primitives.registry import function_op
+
+function_op(
+    name="librt.time.time",
+    arg_types=[],
+    return_type=float_rprimitive,
+    c_function_name="LibRTTime_time",
+    error_kind=ERR_MAGIC_OVERLAPPING,
+    experimental=True,
+    dependencies=[LIBRT_TIME],
+)

mypyc/primitives/registry.py

@@ -394,6 +394,7 @@ def load_address_op(name: str, type: RType, src: str) -> LoadAddressDescription:
 import mypyc.primitives.float_ops
 import mypyc.primitives.int_ops
 import mypyc.primitives.librt_strings_ops
+import mypyc.primitives.librt_time_ops
 import mypyc.primitives.list_ops
 import mypyc.primitives.misc_ops
 import mypyc.primitives.str_ops

mypyc/test-data/irbuild-time.test

@@ -0,0 +1,39 @@
+[case testTime_experimental]
+from librt.time import time
+import librt.time
+
+def t1() -> float:
+    return time()
+
+def t2() -> float:
+    return librt.time.time()
+[out]
+def t1():
+    r0 :: float
+L0:
+    r0 = LibRTTime_time()
+    return r0
+def t2():
+    r0 :: float
+L0:
+    r0 = LibRTTime_time()
+    return r0
+
+[case testTimeExperimentalDisabled]
+from librt.time import time
+
+def get_time() -> float:
+    return time()
+[out]
+def get_time():
+    r0 :: dict
+    r1 :: str
+    r2, r3 :: object
+    r4 :: float
+L0:
+    r0 = __main__.globals :: static
+    r1 = 'time'
+    r2 = CPyDict_GetItem(r0, r1)
+    r3 = PyObject_Vectorcall(r2, 0, 0, 0)
+    r4 = unbox(float, r3)
+    return r4