Emitter

Note

Generated from the C++ headers by apiary --emit-cpp-docs-json.

enum class Target

Selects which Python-binding library the emitter writes against.

Note

Pybind11 is the default, battle-tested target.

Note

Nanobind is newer, ~3-5× faster compile/binary/runtime. Mostly API-compatible with pybind11 but with renamed enums (nb::rv_policy vs py::return_value_policy), a different module macro (NB_MODULE), and a split STL header layout.

Warning

Nanobind has no direct def_buffer analog — buffer protocol directives are dropped under the nanobind target.

enumerator Pybind11

enumerator Nanobind

class DefReport

Per-module tally of binding statements, for sizing --max-defs-per-tu before committing a budget.

int total_defs

All binding statements (.def / .value / register_exception) the module would emit — the quantity --max-defs-per-tu is measured against.

int unit_count

Number of indivisible emit units (one enum, one class instantiation, or one free function). Sharding splits between units, never within one.

int max_unit_defs

Largest single unit’s statement count. A shard can never be smaller than this, so a budget below it yields one oversized shard rather than a finer split.

class EmitOptions

Configuration for a single emit pass.

The emitter has two output shapes:

Note

Standalone module — emit PYBIND11_MODULE(<module_name>, m) { ... } (or NB_MODULE) producing a self-contained .so importable by name. Used by the standalone fixtures and goldens.

Note

Register function — emit void <register_function_name>(<ns>::module_ &m) { ... } which the aggregator main calls from a single module-macro block. Used by the einsums_add_module autogen path so every module ends up under one import einsums.

std::string module_name

module-macro arg (standalone form)

std::string register_function_name

register-function symbol (aggregator form)

std::string source_path_for_format

path used to discover .clang-format

std::vector<std::string> source_includes

headers the bindings refer to (emitted as #include “…”)

Target target

Python-binding library target (defaults to Pybind11).

class ShardFile

One generated shard: its output path and its formatted contents.

std::string path

std::string content

std::string emit(const Module &module_, const EmitOptions &opts)

Emit C++ binding code for module_ and return it as a string.

Output is post-clang-format using the project’s .clang-format if one is found via opts.source_path_for_format; otherwise LLVM style is used.

Parameters:

• module – The IR module to emit bindings for.

• opts – Emit configuration (output shape, target, formatting path, includes).

Returns:

The emitted, clang-formatted C++ binding source.

std::vector<ShardFile> emit_shards(const Module &module_, const EmitOptions &opts, int max_defs, const std::string &base_output_path)

Emit module_’s bindings split across several smaller TUs.

The body is cut into contiguous, order-preserving shards so that no single translation unit exceeds roughly max_defs binding statements. Shard 0 also carries a dispatcher (the register function, or the module macro in standalone form) that calls every <base>__shard<k> in order, so the ordering invariants of the single-TU path are preserved and consumers keep calling one symbol.

When everything fits in a single shard the result is one file at base_output_path whose contents are byte-identical to emit().

Parameters:

• module – The IR module to emit bindings for.

• opts – Emit configuration (output shape, target, formatting path, includes).

• max_defs – Approximate per-TU budget in binding statements (> 0).

• base_output_path – The would-be single-TU path; shard names are derived from it as <stem>.shard<k><ext>.

Returns:

One entry per shard, each with its destination path and contents.

std::vector<std::string> plan_shards(const Module &module_, const EmitOptions &opts, int max_defs, const std::string &base_output_path)

Compute the shard output paths without emitting their contents.

Runs the same partition as emit_shards() so a build system can learn the generated filenames at configure time. Returns { base_output_path } when the module fits in a single TU.

DefReport report_defs(const Module &module_, const EmitOptions &opts)

Tally binding statements for module_ without emitting code.

Uses the same units and cost metric as emit_shards(), so the numbers are directly comparable to a --max-defs-per-tu budget.