[mypyc] Add librt.random module (#21433)

The stdlib `random` module is fairly often used in performance critical
code, and it's not super efficient. Add `librt.random` with a subset of
the stdlib module interface that is optimized for performance when
compiled.

Use ChaCha8 as the algorithm. Based on some research, this is a modern,
high-quality PRNG algorithm. It's used by Go `math/rand/v2`, among
others.

This is a non-cryptographic PRNG, similar to the stdlib `random` module
(but this uses a different algorithm).

I used Claude Code and Codex to write all the code, but I iterated on it
quite a lot and did a bunch of manual validation and code review. I also
asked Codex to explicitly check that the ChaCha8 implementation is
correct by comparing it to a reference implementation.

Use thread-local RNG state for module-level functions to enable good
scaling in free-threaded builds. There's some extra complexity from
having to free the state at thread exit.

I asked a LLM to generate and run a benchmark, and here are the results
on 3.14:
```
    │  Function   │ vs stdlib(compiled) │ vs stdlib(interpreted) │
    │ random()    │        3.2x         │          4.8x          │
    │ randint()   │        16.6x        │         18.0x          │
    │ randrange() │        14.5x        │         16.2x          │
    │ choice()    │        12.9x        │         10.3x          │
```

`choice()` was replaced with `randrange` when using `librt`, since we don't provide it as part of this fairly minimal API.

Author: JukkaL

mypy/typeshed/stubs/librt/librt/random.pyi

@@ -0,0 +1,22 @@
+from typing import final, overload
+
+from mypy_extensions import i64
+
+def random() -> float: ...
+def randint(a: i64, b: i64) -> i64: ...
+@overload
+def randrange(stop: i64, /) -> i64: ...
+@overload
+def randrange(start: i64, stop: i64, /) -> i64: ...
+def seed(n: i64, /) -> None: ...
+
+@final
+class Random:
+    def __init__(self, seed: i64 | None = None) -> None: ...
+    def randint(self, a: i64, b: i64) -> i64: ...
+    @overload
+    def randrange(self, stop: i64, /) -> i64: ...
+    @overload
+    def randrange(self, start: i64, stop: i64, /) -> i64: ...
+    def random(self) -> float: ...
+    def seed(self, n: i64, /) -> None: ...

mypyc/build.py

@@ -121,6 +121,7 @@ class ModDesc(NamedTuple):
         ["vecs"],
     ),
     ModDesc("librt.time", ["time/librt_time.c"], ["time/librt_time.h"], []),
+    ModDesc("librt.random", ["random/librt_random.c"], ["random/librt_random.h"], ["random"]),
 ]
 
 try:
@@ -631,6 +632,9 @@ def get_cflags(
             # Disables C Preprocessor (cpp) warnings
             # See https://github.com/mypyc/mypyc/issues/956
             "-Wno-cpp",
+            "-Wno-array-bounds",
+            "-Wno-stringop-overread",
+            "-Wno-stringop-overflow",
         ]
         if log_trace:
             cflags.append("-DMYPYC_LOG_TRACE")

mypyc/codegen/emitmodule.py

@@ -59,6 +59,7 @@
 from mypyc.errors import Errors
 from mypyc.ir.deps import (
     LIBRT_BASE64,
+    LIBRT_RANDOM,
     LIBRT_STRINGS,
     LIBRT_TIME,
     LIBRT_VECS,
@@ -1224,6 +1225,10 @@ def emit_module_exec_func(
             emitter.emit_line("if (import_librt_vecs() < 0) {")
             emitter.emit_line("return -1;")
             emitter.emit_line("}")
+        if LIBRT_RANDOM in module.dependencies:
+            emitter.emit_line("if (import_librt_random() < 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

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

mypyc/ir/rtypes.py

@@ -41,7 +41,7 @@ class to enable the new behavior. In rare cases, adding a new
 from typing import TYPE_CHECKING, ClassVar, Final, Generic, TypeGuard, TypeVar, Union, final
 
 from mypyc.common import HAVE_IMMORTAL, IS_32_BIT_PLATFORM, PLATFORM_SIZE, JsonDict, short_name
-from mypyc.ir.deps import LIBRT_STRINGS, LIBRT_VECS, Dependency
+from mypyc.ir.deps import LIBRT_RANDOM, LIBRT_STRINGS, LIBRT_VECS, Dependency
 from mypyc.namegen import NameGenerator
 
 if TYPE_CHECKING:
@@ -544,10 +544,15 @@ def __hash__(self) -> int:
         ("librt.strings.BytesWriter", (LIBRT_STRINGS,)),
         ("librt.strings.StringWriter", (LIBRT_STRINGS,)),
     ]
+} | {
+    "librt.random.Random": RPrimitive(
+        "librt.random.Random", is_unboxed=False, is_refcounted=True, dependencies=(LIBRT_RANDOM,)
+    )
 }
 
 bytes_writer_rprimitive: Final = KNOWN_NATIVE_TYPES["librt.strings.BytesWriter"]
 string_writer_rprimitive: Final = KNOWN_NATIVE_TYPES["librt.strings.StringWriter"]
+random_rprimitive: Final = KNOWN_NATIVE_TYPES["librt.random.Random"]
 
 
 def is_native_rprimitive(rtype: RType) -> bool: