ADR-0044: Run a library's module when it loads and guard each export¶
Status¶
Accepted
Date¶
2026-11-17
Context¶
ADR-0032 decides what a library built with typy build --lib exports: the
functions its module's __all__ lists, with C types from their
annotations. It leaves open how such a library runs inside a program that
TyPy did not build, which CLI-09, FFI-05 and EXC-05 need for 0.5.
An executable starts in the runtime's main, which records the stack
limit the recursion check uses, keeps the arguments for sys.argv, runs
the module bodies through __typy_main, reports an exception nothing
caught, and flushes standard output and closes files at the end. A library
has no main of its own, and the program that loads it may be in C, C++,
Rust or Python. Experiments with the 0.5 runtime archive show three things
that decide the design:
- The runtime archive is one object, built with LTO, that defines
main. A partial link of the program's object with it, with every global symbol but the exports made local, gives a static library that a C program with its ownmainlinks. A shared library linked with a version script that exports only the exports loads into CPython throughctypes. - Without the runtime's
main, nothing flushes the runtime's buffer of standard output: aprintin the library's module never appears. - The recursion check compares the stack pointer with a limit recorded when
mainstarts. A call from another thread runs on another stack, where the check would fire at once or never.
Options considered¶
For when the module bodies run:
- When the library loads, from a constructor in
.init_array: when the program starts for a library it links, and indlopenfor one it loads later, asctypes.CDLLdoes. This is when CPython runs a module's body: when it is imported, before any of its functions is called. - At the first call of an export, behind a test on every call. A library whose exports are never called never runs its body, and the body's output lands in the middle of the program's.
- In an initialising function the host calls, as many C libraries ask. A host that forgets it calls functions whose module variables have no values.
For the runtime's symbols in a static library:
- Leave them global. A program that links two TyPy libraries, or a TyPy library into a TyPy program, gets every runtime symbol twice.
- Make every symbol but the exports local, after a partial link of the program object and the runtime archive into one object. Each library keeps a runtime of its own, as each shared library does.
Decision¶
TyPy uses option 1 for when the module bodies run, and option 2 for the symbols.
- The module. The main file of a library build is a module named
after its file, so
mathlib.pyismathlib, its__name__, andif __name__ == "__main__":code does not run, as on an import.sys.argvis[''], as in an embedded CPython. - Loading. The object of a library has a constructor that records the
stack limit, runs the module bodies and flushes standard output. An
exception the bodies raise is handled as one that leaves an export.
A destructor flushes standard output and closes the files the program
opened, as
maindoes when it ends. - Each export. The C symbol is the function's name, and calls a
wrapper that records the stack limit from the calling thread's stack
pointer, converts each argument from its C type, calls the function,
converts the result, and flushes standard output, so the library's
output and the host's keep their order.
int,floatandboolareint64_t,doubleandbool, and a result of typeNoneisvoid; anintresult outsideint64_traisesOverflowError. - An exception that leaves an export never reaches C (EXC-05): a
SystemExitends the process with its status, as when it leaves a program's module, and any other exception is printed as an uncaught exception is, and the process aborts. - Names.
__all__is a list or tuple of string literals bound once at module level, and each name is a function of the module with positional parameters, no type parameters, and parameters and a result of the types above. An export may not be namedmain, start withtypy_,__typyor_TY, or be a C library function the runtime calls, such asreadorfree, since inside the library its definition would take that function's place. Each problem is E0428, which names the export. - Threads. The runtime's state is not shared safely between threads, so a host calls a library's exports from one thread at a time.
- Linking. A static library is the program object and the runtime
archive linked into one object with
cc -r, its global symbols but the exports made local withobjcopy --keep-global-symbols, in an archive made withar. A shared library is linked withcc -sharedand a version script that exports only the exports. The runtime'smainstays in the archive and is local or unexported in both. The output islibNAME.aorlibNAME.sobeside the main file unless-onames another path, and the C headerNAME.his written beside it.
Consequences¶
- A library behaves as an imported module: its body runs once, before any
export is called, and a C program, a Python program through
ctypesand a TyPy program see the same output in the same order. - Each library carries the runtime, about 1 MiB in a static library before the host's linker removes what no export reaches.
- Every call of an export pays for recording the stack limit and testing the output buffer, a few instructions beside the call.
- A static library needs
objcopyandarbesides the C compiler, which the binutils of every Linux C toolchain provide (A-01). - The recursion check of a call from a thread assumes the thread has the
stack size
getrlimitgives below the call, which is glibc's default for a new thread.
Related requirements¶
CLI-09, FFI-05, EXC-05, FUN-02, STD-05, LIB-04, A-01, ADR-0032, ADR-0043.