How Python’s Heart Stays Safe at Full Speed

Where ceval.c Fits in CPython

ceval.c is not a helper; it is the interpreter. Almost everything that “runs” in Python eventually passes through its main eval loop.

cpython/
  Python/
    ceval.c          # Core evaluation loop, stack & frame management, helpers
    ceval.h
    ceval_macros.h
    opcode_targets.h
    generated_cases.c.h
    executor_cases.c.h
  Objects/
    frameobject.c    # Frame object implementation
    funcobject.c     # Function object implementation
    dictobject.c     # Dict implementation used by globals/builtins
  Modules/
    _import.c        # Import machinery using helpers from ceval.c

PyEval_EvalCode
  -> _PyFunction_FromConstructor
  -> _PyEval_Vector
       -> _PyEvalFramePushAndInit
            -> initialize_locals
       -> _PyEval_EvalFrame
            -> _PyEval_EvalFrameDefault

_PyEval_EvalFrameDefault is effectively Python’s CPU: it fetches bytecode, manipulates a small value stack, and delegates heavier work (calls, imports, pattern matching) to focused helpers.

To keep this heart safe at full speed, CPython wraps it with layered protections: recursion limits, stack bounds, disciplined argument binding, explicit ownership rules, and clear import policies. The rest of this article walks through those layers and the design patterns behind them.

The Safety Net Around the Eval Loop

Deep recursion and uncontrolled call chains are where high‑performance interpreters tend to crash. CPython defends its eval loop with two coordinated mechanisms: a Python‑level recursion limit and platform‑aware C stack bounds.

Python‑level recursion: changing a global knob safely

From Python, recursion control looks like a single global limit. Underneath, changing it must keep all threads consistent:

int
Py_GetRecursionLimit(void)
{
    PyInterpreterState *interp = _PyInterpreterState_GET();
    return interp->ceval.recursion_limit;
}

void
Py_SetRecursionLimit(int new_limit)
{
    PyInterpreterState *interp = _PyInterpreterState_GET();
    _PyEval_StopTheWorld(interp);
    interp->ceval.recursion_limit = new_limit;
    _Py_FOR_EACH_TSTATE_BEGIN(interp, p) {
        int depth = p->py_recursion_limit - p->py_recursion_remaining;
        p->py_recursion_limit = new_limit;
        p->py_recursion_remaining = new_limit - depth;
    }
    _Py_FOR_EACH_TSTATE_END(interp);
    _PyEval_StartTheWorld(interp);
}

The pattern is straightforward but important: stop the world, update all per‑thread recursion counters based on their current depth, then resume. For safety‑critical global knobs, consistency comes before mutation.

C stack bounds: guarding against hard crashes

The logical recursion counter is not enough. The underlying C stack can overflow earlier depending on platform and calling patterns. CPython estimates stack bounds per thread and enforces them in _Py_CheckRecursiveCall():

int
_Py_CheckRecursiveCall(PyThreadState *tstate, const char *where)
{
    _PyThreadStateImpl *_tstate = (_PyThreadStateImpl *)tstate;
    uintptr_t here_addr = _Py_get_machine_stack_pointer();
    assert(_tstate->c_stack_soft_limit != 0);
    assert(_tstate->c_stack_hard_limit != 0);
#if _Py_STACK_GROWS_DOWN
    assert(here_addr >= _tstate->c_stack_hard_limit - _PyOS_STACK_MARGIN_BYTES);
    if (here_addr < _tstate->c_stack_hard_limit) {
        /* Overflowing while handling an overflow. Give up. */
        int kbytes_used = (int)(_tstate->c_stack_top - here_addr)/1024;
        char buffer[80];
        snprintf(buffer, 80, "Unrecoverable stack overflow (used %d kB)%s", kbytes_used, where);
        Py_FatalError(buffer);
    }
#endif
    if (tstate->recursion_headroom) {
        return 0;
    }
    else {
        int kbytes_used = (int)(_tstate->c_stack_top - here_addr)/1024;
        tstate->recursion_headroom++;
        _PyErr_Format(tstate, PyExc_RecursionError,
                    "Stack overflow (used %d kB)%s",
                    kbytes_used,
                    where);
        tstate->recursion_headroom--;
        return -1;
    }
}

• Two‑tier protection: a soft Python recursion counter plus a hard C stack margin. Both must hold for the system to stay healthy.
• Unrecoverable paths are explicit: if an overflow happens while handling an existing overflow, CPython treats that as fatal. Continuing would mean running with broken invariants.

Taming Argument Binding Complexity

Every Python function call eventually hits CPython’s argument binder. In ceval.c, that logic lives in initialize_locals(), which maps positional arguments, keywords, *args, **kwargs, defaults, and keyword‑only parameters into a flat frame array.

A trimmed version shows the core responsibilities: setting up **kwargs, copying positionals, and resolving keywords:

static int
initialize_locals(PyThreadState *tstate, PyFunctionObject *func,
    _PyStackRef *localsplus, _PyStackRef const *args,
    Py_ssize_t argcount, PyObject *kwnames)
{
    PyCodeObject *co = (PyCodeObject*)func->func_code;
    const Py_ssize_t total_args = co->co_argcount + co->co_kwonlyargcount;
    PyObject *kwdict;

    if (co->co_flags & CO_VARKEYWORDS) {
        kwdict = PyDict_New();
        if (kwdict == NULL) {
            goto fail_pre_positional;
        }
        Py_ssize_t i = total_args;
        if (co->co_flags & CO_VARARGS) {
            i++;
        }
        assert(PyStackRef_IsNull(localsplus[i]));
        localsplus[i] = PyStackRef_FromPyObjectSteal(kwdict);
    }
    else {
        kwdict = NULL;
    }

    /* Copy positional arguments */
    Py_ssize_t j, n;
    if (argcount > co->co_argcount) {
        n = co->co_argcount;
    }
    else {
        n = argcount;
    }
    for (j = 0; j < n; j++) {
        assert(PyStackRef_IsNull(localsplus[j]));
        localsplus[j] = args[j];
    }

    /* Pack extra positionals into *args */
    if (co->co_flags & CO_VARARGS) {
        ...
    }

    /* Handle keyword arguments */
    if (kwnames != NULL) {
        Py_ssize_t kwcount = PyTuple_GET_SIZE(kwnames);
        for (Py_ssize_t i = 0; i < kwcount; i++) {
            PyObject **co_varnames;
            PyObject *keyword = PyTuple_GET_ITEM(kwnames, i);
            _PyStackRef value_stackref = args[i+argcount];

            if (keyword == NULL || !PyUnicode_Check(keyword)) {
                _PyErr_Format(tstate, PyExc_TypeError,
                            "%U() keywords must be strings",
                          func->func_qualname);
                goto kw_fail;
            }

            co_varnames = ((PyTupleObject *)(co->co_localsplusnames))->ob_item;
            /* Fast pointer compare, then slow rich-compare fallback */
            ...
        }
    }

    /* Check positional count, then fill defaults & kwonly defaults */
    ...

    return 0;

fail_pre_positional:
    ...
fail_post_args:
    return -1;
}

This function is responsible for the friendly call‑site errors you see every day: missing required arguments, arguments passed twice, positional‑only vs keyword‑only misuse, and “Did you mean” suggestions. Unsurprisingly, its size and cyclomatic complexity are high.

The static analysis report suggests splitting initialize_locals() into helpers such as bind_positional_args, bind_keyword_args, and apply_default_values. Each phase would own one part of the calling convention with clear invariants:

A function’s argument binder is essentially its calling convention. Keeping it monolithic makes changes risky; breaking it into explicit phases makes it testable and evolvable without compromising speed.

Fast StackRefs with Explicit Ownership

Executing bytecode quickly means moving values around cheaply. CPython’s internal _PyStackRef abstraction represents values on the interpreter stack in a way that’s GC‑visible and cheap to pass. The flip side: ownership rules get subtle, and subtle ownership bugs are catastrophic.

_Py_VectorCall_StackRefSteal() shows how CPython enforces those rules while driving fast calls:

PyObject *
_Py_VectorCall_StackRefSteal(
    _PyStackRef callable,
    _PyStackRef *arguments,
    int total_args,
    _PyStackRef kwnames)
{
    PyObject *res;
    STACKREFS_TO_PYOBJECTS(arguments, total_args, args_o);
    if (CONVERSION_FAILED(args_o)) {
        res = NULL;
        goto cleanup;
    }
    PyObject *callable_o = PyStackRef_AsPyObjectBorrow(callable);
    PyObject *kwnames_o = PyStackRef_AsPyObjectBorrow(kwnames);
    int positional_args = total_args;
    if (kwnames_o != NULL) {
        positional_args -= (int)PyTuple_GET_SIZE(kwnames_o);
    }
    res = PyObject_Vectorcall(
        callable_o, args_o,
        positional_args | PY_VECTORCALL_ARGUMENTS_OFFSET,
        kwnames_o);
    STACKREFS_TO_PYOBJECTS_CLEANUP(args_o);
    assert((res != NULL) ^ (PyErr_Occurred() != NULL));
cleanup:
    PyStackRef_XCLOSE(kwnames);
    // arguments is a pointer into the GC visible stack,
    // so we must NULL out values as we clear them.
    for (int i = total_args-1; i >= 0; i--) {
        _PyStackRef tmp = arguments[i];
        arguments[i] = PyStackRef_NULL;
        PyStackRef_CLOSE(tmp);
    }
    PyStackRef_CLOSE(callable);
    return res;
}

• Ownership in the name: the StackRefSteal suffix states that this function consumes its arguments. Callers must not touch those stackrefs afterward.
• GC‑visible invariants: because the stack is visible to the garbage collector, clearing an entry means both closing it and nulling out the slot. Dead pointers on a GC‑visible stack are a correctness bug, not just a leak.
• Unified cleanup: both success and failure paths share a single cleanup block, encoding ownership rules in one place instead of scattering them.

The report notes that these contracts are enforced but not always loudly documented; several helpers (_Py_LoadAttr_StackRefSteal, _Py_BuildMap_StackRefSteal, etc.) follow the same pattern. The recommended direction is to make invariants explicit through naming, comments, and assertions, not just convention.

Lazy Imports and Hidden Latency

Imports are another place where performance optimizations can quietly undermine predictability. CPython’s lazy import machinery can defer importing a module until first use, improving startup time but shifting work into later, potentially hot, code paths.

Global loads that may trigger imports

Global name access goes through _PyEval_LoadGlobalStackRef(), which first tries to resolve the name and then, if it finds a lazy import object, performs the actual import:

void
_PyEval_LoadGlobalStackRef(PyObject *globals, PyObject *builtins,
                           PyObject *name, _PyStackRef *writeto)
{
    if (PyAnyDict_CheckExact(globals) && PyAnyDict_CheckExact(builtins)) {
        _PyDict_LoadGlobalStackRef((PyDictObject *)globals,
                                   (PyDictObject *)builtins,
                                   name, writeto);
        if (PyStackRef_IsNull(*writeto) && !PyErr_Occurred()) {
            _PyEval_FormatExcCheckArg(PyThreadState_GET(), PyExc_NameError,
                                      NAME_ERROR_MSG, name);
        }
    }
    else {
        /* Slow-path: non-dict globals/builtins */
        ...
    }

    PyObject *res_o = PyStackRef_AsPyObjectBorrow(*writeto);
    if (res_o != NULL && PyLazyImport_CheckExact(res_o)) {
        PyObject *l_v = _PyImport_LoadLazyImportTstate(PyThreadState_GET(), res_o);
        PyStackRef_CLOSE(writeto[0]);
        if (l_v == NULL) {
            assert(PyErr_Occurred());
            *writeto = PyStackRef_NULL;
            return;
        }
        int err = PyDict_SetItem(globals, name, l_v);
        if (err < 0) {
            Py_DECREF(l_v);
            *writeto = PyStackRef_NULL;
            return;
        }
        *writeto = PyStackRef_FromPyObjectSteal(l_v);
    }
}

A global lookup that usually behaves like a dictionary read can, the first time it encounters a lazy symbol, perform a full module import. That’s a one‑off latency spike hidden inside a hot path.

Separating lazy import policy from mechanics

Whether a particular import is lazy is decided in _PyEval_LazyImportName(), which currently mixes “should this be lazy?” with the actual import operations:

PyObject *
_PyEval_LazyImportName(PyThreadState *tstate, PyObject *builtins,
                       PyObject *globals, PyObject *locals, PyObject *name,
                       PyObject *fromlist, PyObject *level, int lazy)
{
    PyObject *res = NULL;
    // Check if global policy overrides the local syntax
    switch (PyImport_GetLazyImportsMode()) {
        case PyImport_LAZY_NONE:  lazy = 0; break;
        case PyImport_LAZY_ALL:   lazy = 1; break;
        case PyImport_LAZY_NORMAL: break;
    }

    if (!lazy && PyImport_GetLazyImportsMode() != PyImport_LAZY_NONE) {
        // See if __lazy_modules__ forces this to be lazy.
        lazy = check_lazy_import_compatibility(tstate, globals, name, level);
        if (lazy < 0) {
            return NULL;
        }
    }

    if (!lazy) {
        return _PyEval_ImportName(tstate, builtins, globals, locals,
                                  name, fromlist, level);
    }

    PyObject *lazy_import_func;
    if (PyMapping_GetOptionalItem(builtins, &_Py_ID(__lazy_import__),
                                  &lazy_import_func) < 0) {
        goto error;
    }
    ...
}

The analysis recommends factoring out a helper that answers only “is lazy import enabled here?”. That separation has concrete benefits:

• You can reason about and test lazy import policy independently of import mechanics.
• Instrumentation (e.g., counting lazy decisions) has a focused insertion point.
• Changes to import mechanics are less likely to accidentally change policy.

Metrics That Keep the Core Honest

ceval.c is the engine under every Python application, so even small changes can have global impact. Instead of guessing, CPython uses a set of focused metrics that you can mirror when embedding Python or building similar runtimes.

• python.eval.bytecode_instructions_per_second – interpreter throughput. If this moves, everything moves.
• python.eval.frames_pushed_per_second – how call‑heavy workloads are. High values highlight expensive call patterns: layers of decorators, dynamic dispatch, or tiny functions in tight loops.
• python.eval.lazy_import_resolution_time_ms – latency impact from lazy imports. Tracking this, especially high percentiles, tells you whether startup wins are turning into runtime spikes.
• python.eval.recursion_error_count – pressure on recursion safeguards. Non‑zero values in production indicate either mis‑use (unbounded recursion) or mis‑configuration (limits set too low).

Treat the interpreter like a service with its own SLOs: throughput, latency spikes, and error rates. That’s how you keep a core engine both fast and honest as you evolve it.

Design Lessons You Can Apply

The common thread across recursion limits, argument binding, stackrefs, and lazy imports is a single principle: CPython keeps its core fast by making safety explicit—through layered limits, clear ownership, and well‑bounded complexity—rather than by hoping nothing goes wrong.

From this tour of ceval.c, a few concrete practices are worth carrying into your own high‑performance subsystems:

• Layer your safeguards. Use both logical and physical limits: counters plus resource bounds. Be explicit about unrecoverable paths instead of pretending they don’t exist.
• Isolate complex calling conventions. Argument binding logic deserves dedicated phases, clear invariants, and its own tests. That keeps your “execution core” lean and predictable.
• Make ownership rules visible. In low‑level code, encode ownership in names, documentation, and assertions. Contracts like “steals” vs “borrows” should be obvious even to someone new to the codebase.
• Defer work with discipline. Lazy features help benchmarks, but they reshape latency. Separate “should we be lazy?” from “how do we do the work?” and instrument both.
• Instrument the engine, not just the app. Metrics on frame creation, recursion errors, and lazy resolution times reveal how your runtime behaves under real workloads, not just how your business logic behaves.

If a single, dense C file can execute most of the world’s Python code without routinely crashing, it’s because its authors designed for speed and safety together. The next time you design a critical core—an interpreter, scheduler, or request router—ask explicitly: where are my limits, how do I enforce them, and how will I know when they start to bend?