Every point cloud above was computed in plain C++ and reached Python through a binding I didn’t write. No .def(), no trampoline classes, no keyword-arg boilerplate. Just bind_class<PointCloud>(m, "PointCloud"). Reflection fills in the rest at compile time.

TL;DR

• 47 Open3D geometry classes bind with 0 hand-written lines. mirror_bridge generate emits the whole 71-line module.
• On the list-to-std::vector<Eigen::Vector3d> ingest primitive, mirror_bridge is 30-35× faster than pybind11, stable across 10K-1M points. On compute-heavy calls the binding layer rounds to zero and the two frameworks are at parity. Full case study in §3.
• Apache 2.0. One docker run reproduces every number in under ten minutes.

1. pybind11: write every binding twice

Here’s how Open3D binds one method, voxel_down_sample_and_trace (pointcloud.cpp L70-L75):

.def("voxel_down_sample_and_trace",
     &PointCloud::VoxelDownSampleAndTrace,
     "Function to downsample using PointCloud::VoxelDownSample. Also "
     "records point cloud index before downsampling",
     "voxel_size"_a, "min_bound"_a, "max_bound"_a,
     "approximate_class"_a = false)

Every method lives twice: once in the class declaration, again here. Every parameter name is re-typed. Every default is re-typed. Every overload gets its own .def().

The pybind11 layer for Open3D’s geometry module alone is 3,610 lines. The whole Python binding spans 25,262 lines across 124 files.

2. mirror_bridge: write nothing

One command. Zero hand-written binding code:

$ mirror_bridge generate Open3D/cpp/open3d/geometry \
      --module open3d_full --lang python \
      -I Open3D/cpp -I /usr/include/eigen3

  ✓ Found: OrientedBoundingBox in BoundingVolume.h
  ✓ Found: AxisAlignedBoundingBox in BoundingVolume.h
  ✓ Found: HalfEdgeTriangleMesh::HalfEdge in HalfEdgeTriangleMesh.h
  ✓ Found: KDTreeSearchParam::SearchType in KDTreeSearchParam.h
  ✓ Found: TriangleMesh::Material::MaterialParameter in TriangleMesh.h
  ✓ Found: VoxelGrid::VoxelPoolingMode in VoxelGrid.h
     ... 47 classes in all ...
  ✓ Built: build/open3d_full.so

A brace-depth parser finds every class, struct and enum. Nested types get qualified correctly (HalfEdgeTriangleMesh::HalfEdge, not a bare HalfEdge that would collide with another file’s HalfEdge).

Dependencies are resolved by reflection, not by the parser. std::meta::bases_of(T) gives inheritance edges. The enclosing scope gives nesting. parameters_of and the reflected return type catch every class referenced from a method signature. The generator topologically sorts the result, so AxisAlignedBoundingBox lands before PointCloud (which returns one from get_aabb()), and every nested type lands after its enclosing scope.

The emitted module is short enough to read:

MIRROR_BRIDGE_MODULE(open3d_full,
    mirror_bridge::bind_class<OrientedBoundingBox>(m, "OrientedBoundingBox");
    mirror_bridge::bind_class<AxisAlignedBoundingBox>(m, "AxisAlignedBoundingBox");
    mirror_bridge::bind_class<PointCloud>(m, "PointCloud");
    // ... 43 more bind_class lines ...
    mirror_bridge::bind_class<AggColorVoxel>(m, "AggColorVoxel");
)

71 lines total. Each bind_class<T> pulls constructors, methods, fields, operators, kwargs, defaults, __repr__, subclassing, inheritance and polymorphic returns straight from the header.

3. Deep dive: 30× faster on list → vector<Eigen::Vector3d>

The binding layer only matters when it is the whole cost. Computing a centroid on a million points is SIMD math; the dispatcher rounds to zero. But constructing the point cloud from a Python list is pure binding-layer work, and that’s where mirror_bridge is dramatically faster than pybind11.

The measurement

Both bindings are compiled against the same demo::PointCloud source in asm_study/geometry_min.hpp, with the same clang-p2996 and the same -O3 -stdlib=libc++ -fPIC -shared flags. The only thing that changes between pc_pybind.so and pc_mb.so is the binding framework.

Constructor scaling on a list of 3-element float sublists, median of 3 runs with one warmup (source):

The ratio is stable. This is a constant-factor binding-layer difference, not a scaling artefact.

For context, at N = 1M on the same build:

Parity on compute. A clean 3× on dispatch. 30× on the ingest primitive.

Why pybind11 pays that cost

pybind11’s type_caster<Eigen::Matrix<double, 3, 1>> is designed first for numpy compatibility and second for Python lists. On every element, it:

1. Constructs a caster object.
2. Checks whether the element is a numpy array of the right dtype and shape.
3. Falls through to the Python buffer protocol.
4. Falls through to the “length-3 sequence of floats” path.
5. Constructs a fresh Eigen::Vector3d and emits a move into the destination vector.

Every one of a million elements pays steps 1-5. For list input, the numpy and buffer-protocol checks are pure overhead.

Why mirror_bridge doesn’t

mirror_bridge’s eigen_vector_from_python is specialised for the list shape. No numpy branches, no caster objects, no detours:

// from python/mirror_bridge_eigen.hpp (abridged)
template<typename Scalar, int N>
inline bool eigen_vector_from_python(PyObject* obj,
                                     Eigen::Matrix<Scalar, N, 1>& out) {
    if (!PySequence_Check(obj) || PySequence_Size(obj) != N) return false;
    for (int i = 0; i < N; i++) {
        PyObject* item = PySequence_GetItem(obj, i);
        out[i] = static_cast<Scalar>(PyFloat_AsDouble(item));
        Py_DECREF(item);
    }
    return true;
}

The outer list→vector loop (in mirror_bridge_python.hpp) calls this per element. Three PyFloat_AsDouble calls and a direct write into the Eigen object. No intermediate ceremony.

Reflection is what makes this specialisation possible: at binding- generation time, mirror_bridge knows the parameter type is std::vector<Eigen::Vector3d>, so it can emit the specialised converter in the call site. pybind11’s type caster has no comparable compile-time information and has to handle the general case every time.

Reproduce

One-time: ./docker_build.sh compiles clang-p2996 and libc++ from source (~18 minutes on a modern laptop, measured). Every run after the image is built is ~15 seconds.

git clone https://github.com/FranciscoThiesen/mirror_bridge
cd mirror_bridge
./docker_build.sh                   # one-time, ~18 min

docker run --rm -v $(pwd):/workspace -w /workspace/asm_study \
    mirror_bridge:latest bash -c '\
        ./build_fair.sh && \
        python3 bench_fair.py'

build_fair.sh compiles both bind_mb.cpp and bind_pybind.cpp with identical flags, printing the exact compiler line. bench_fair.py prints the scaling table above plus the context rows. Expect constants in the 25-40× range depending on hardware; the scaling pattern holds.

When it matters in practice

• Data pipelines that parse JSON / CSV / dicts into C++ types hit this ingest primitive. The 30× compounds across a batch job.
• Compute-dominated workflows where you load a million points once and then run a dozen C++ methods on them: ingest amortises, the rest is at parity. No win, no loss.
• Numpy already: both frameworks can use the buffer protocol for near-zero-copy access. If your data is already a numpy array, use that. mirror_bridge has an open item to expose PointCloud.points through the buffer protocol directly, which would collapse this entire cost to a pointer handoff.

4. What the FFI still costs

Even on the fast side, crossing the FFI isn’t free:

Handing a million points into C++ is a real 1M-vector copy. Reading them back as a Python list re-materialises a million Python objects.

Rule of thumb: keep data inside C++ as long as possible, and only extract what you display. Every parity number above holds because the points live in the C++ PointCloud and each method call returns a small scalar.

5. Everything reflection can see is free

Auto-generated per class, no user input:

• Constructors as Python __init__ overloads, resolved by arg count and type.
• Methods, direct and inherited via bases_of BFS walk.
• Fields as Python attributes (getter/setter).
• Operators: + - * / % == != < > <= >= += -= *= /= [] () and unary +/-. Routed via std::meta::operator_of to the matching Python slot.
• Keyword arguments from std::meta::identifier_of on each parameter info.
• Default argument values detected via has_default_argument.
• __repr__ from visible members.
• Exception mapping: std::out_of_range → IndexError, std::invalid_argument → ValueError, std::runtime_error → RuntimeError, via dynamic_cast.
• Polymorphic returns resolved through typeid lookup.
• Nested classes qualified as Parent::Child.

Auto-trampoline: Python subclasses override C++ virtuals for free

pybind11 lets Python subclasses override C++ virtuals, but the plumbing isn’t free. You have to write a trampoline class: a hand-forwarded layer with one entry per virtual, each using PYBIND11_OVERRIDE(...) to route back to Python if the subclass defined an override. One class, one trampoline. Ten classes, ten.

mirror_bridge generates the trampoline from reflection. bind_class_auto<T> enumerates T’s virtual slots, synthesises a per-slot dispatcher that routes into Python when the instance has an override, and swaps T’s vtable with a custom one at construction. You write zero glue.

class TaggedPointCloud(o3d.PointCloud):
    def GetCenter(self):
        return [999, 999, 999]   # reached by C++ too, via the vtable swap

No PYBIND11_OVERRIDE, no dispatch helper, no trampoline boilerplate. (Caveat: works on Linux and macOS today; see §8.)

6. Running against real libOpen3D.so

This isn’t a theoretical exercise. The binding loads and calls into a real libOpen3D.so built from source. Getting there took two small CMake patches to a single file (3rdparty/find_dependencies.cmake):

1. Forward CMAKE_CXX_FLAGS to ExternalProjects so 3rdparty libraries (VTK, embree, zmq, …) inherit -stdlib=libc++ from the top-level build. Without it, the final .so mixes std::__1::* (libc++) and std::__cxx11::* (libstdc++) symbols and fails to dlopen.

2. Wrap BoringSSL archives with -Wl,--whole-archive when linking libOpen3D.so, or dlopen fails on X509_INFO_free (curl and zmq reach SSL through transitive calls the linker otherwise drops).

The diff lives at examples/open3d-full-port/patches as a single .patch file. macOS and Windows builds are unchanged.

With the patched fork, a real Open3D Python session (source):

import real_open3d as o3d

pcd = o3d.PointCloud([[0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]])
print(pcd.GetCenter())             # [0.25, 0.25, 0.25]
print(pcd.HasPoints())             # True

smaller = pcd.VoxelDownSample(voxel_size=0.5)   # kwargs + defaults
aabb    = pcd.GetAxisAlignedBoundingBox()        # polymorphic return
print(aabb.Volume())                              # 1.0

# Subclass Open3D with a Python override. No trampoline.
class TaggedPointCloud(o3d.PointCloud):
    def GetCenter(self):
        return [999, 999, 999]

Zero .def calls.

7. Try it yourself

The one-time toolchain build takes ~18 minutes (compiling clang-p2996 + libc++ from source). After that, the reproduction steps below run in well under a minute.

git clone https://github.com/FranciscoThiesen/mirror_bridge
cd mirror_bridge
./docker_build.sh                   # one-time, ~18 min

Quick reproduction (~20 seconds in a built image)

docker run --rm -v $(pwd):/workspace -w /workspace mirror_bridge:latest bash -c '
    # The §3 ingest benchmark:
    cd asm_study && ./build_fair.sh && python3 bench_fair.py && \
    # The 6-panel visual at the top of this post:
    cd ../examples/open3d-comprehensive && \
    ./build_and_test.sh && python3 visual_demo.py
'

Measured end-to-end: ~18 seconds on an Apple Silicon laptop. open3d-comprehensive/build_and_test.sh verifies 10 feature groups; visual_demo.py writes mirror_bridge_open3d_demo.png. No external downloads required beyond what ./docker_build.sh already pulled.

Extended: link against real libOpen3D.so (~15 minutes extra)

The examples/open3d-runtime/ demo links against a real libOpen3D.so you build once from the patched fork. The full recipe (inside the Docker container, from the repo root):

# Build libOpen3D.so. ~5 minutes on a modern laptop; the 3rdparty
# tarballs are already cached in examples/open3d-full-port/Open3D/
# 3rdparty_downloads so no internet round trips are needed.
mkdir -p /tmp/o3d_fork_build && cd /tmp/o3d_fork_build
cmake -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_CXX_FLAGS="-stdlib=libc++" \
  -DBUILD_SHARED_LIBS=ON \
  -DBUILD_GUI=OFF -DBUILD_PYTHON_MODULE=OFF -DBUILD_EXAMPLES=OFF \
  -DBUILD_TESTS=OFF -DBUILD_BENCHMARKS=OFF -DBUILD_UNIT_TESTS=OFF \
  -DBUILD_WEBRTC=OFF -DBUILD_LIBREALSENSE=OFF -DBUILD_AZURE_KINECT=OFF \
  -DUSE_SYSTEM_EIGEN3=ON \
  /workspace/examples/open3d-full-port/Open3D
ninja ext_openblas   # openblas first; Open3D's ExternalProject
                     # wiring otherwise asks for libopenblas.a
                     # before it's been staged.
ninja                # the rest (~3-4 minutes)

# Build and run the mirror_bridge binding against it (~17 seconds):
cd /workspace/examples/open3d-runtime
export O3D_BUILD=/tmp/o3d_fork_build
./build_and_test.sh                 # 5 feature groups pass

A note on LD_PRELOAD. Open3D’s vendored 3rdparty deps (curl, zmq, parts of VTK) compile with libstdc++ even when the top-level build requests libc++, so the resulting libOpen3D.so carries unresolved std::__cxx11::* symbols. libc++ and libstdc++ use different symbol namespaces (std::__1:: vs std::__cxx11::), so the two can coexist in one process; build_and_test.sh preloads libstdc++ so the loader finds those symbols at dlopen time. This does not affect the mirror_bridge binding’s ABI, which stays pure libc++.

8. What it isn’t yet

• Compiler support. Needs C++26 reflection (P2996). That means clang-p2996 today (pinned in the Docker image) or GCC 15 trunk. MSVC hasn’t implemented P2996. That’s the real portability ceiling right now.

• Auto-trampoline is Linux/macOS only (Itanium ABI). On MSVC the portable bind_class<T, Trampoline> path still works: you write a small trampoline class that forwards each virtual to dispatch_python<Ret>("name"). Same behaviour, a few lines per virtual of hand-written glue.

• Default argument values aren’t exposed by P2996R13, only their presence. You can skip trailing defaulted args in a kwargs call; you can’t skip a middle one and supply a later one.

• Docstrings. P2996 doesn’t expose Doxygen comments. Workarounds exist ([[=mb::doc("...")]] via P3394, or a parallel parser). Not shipping today.

Star the repo, tell us what to bind next

mirror_bridge is Apache 2.0 at FranciscoThiesen/mirror_bridge. It emits Python, Lua and JavaScript bindings today from the same C++ reflection input.

If you’ve ever written a pybind11 .def() chain for a hundred-method class and wished there was a better way, this is it.

If the numbers surprised you, run the reproduction and try to break them. If you hit something that doesn’t work, file an issue. The repo is small and feedback drives priorities.

⭐ GitHub: github.com/FranciscoThiesen/mirror_bridge

Thanks to the clang-p2996 team at Bloomberg and the P2996 author community. None of this is possible without their reflection work.

TL;DR: mirror_hash uses C++26 reflection to automatically generate hash functions for any class/struct. No macros, no annotations, no manual member lists. A trivially copyable Point{int, int} hashes in under 2ns. Passes all SMHasher tests. Works today with clang-p2996.

Writing std::hash specializations is one of those C++ rituals that nobody enjoys. You’ve probably done something like:

struct Point {
    int x, y;
    bool operator==(const Point&) const = default;
};

// Now you have to write this boilerplate:
template<>
struct std::hash<Point> {
    std::size_t operator()(const Point& p) const noexcept {
        std::size_t seed = 0;
        // boost::hash_combine pattern
        seed ^= std::hash<int>{}(p.x) + 0x9e3779b9 + (seed << 6) + (seed >> 2);
        seed ^= std::hash<int>{}(p.y) + 0x9e3779b9 + (seed << 6) + (seed >> 2);
        return seed;
    }
};

This pattern is based on boost::hash_combine.

For every single type you want to use in an unordered_map (or any hash table). And when your struct changes? Update the hash function. Forget a member? Silent bugs. Add a pointer to a vector? Now you need to think about whether to hash the pointer or the contents.

What if I told you C++26 can do this automatically?

Enter C++26 Reflection

C++26’s reflection proposal (P2996) gives us the ability to introspect types at compile time. We can iterate over struct members, get their names, types, and values, all without macros or code generation.

Here’s the core idea behind mirror_hash:

#include "mirror_hash/mirror_hash.hpp"

struct Point {
    int x, y, z;
    bool operator==(const Point&) const = default;
};

int main() {
    Point p{10, 20, 30};

    // Just works. No specialization needed.
    auto h = mirror_hash::hash(p);

    // Works with standard containers too
    std::unordered_set<Point, mirror_hash::hasher<>> points;
    points.insert({1, 2, 3});
}

No boilerplate. No manual member enumeration. It just works.

And it’s not limited to simple types. Complex nested structures work automatically:

struct User {
    std::string name;
    int age;
    std::vector<std::string> tags;
    std::optional<std::string> email;
};

std::unordered_map<User, Data, mirror_hash::hasher<>> users;
users[{"Alice", 30, {"admin", "dev"}, "alice@example.com"}] = data;

Strings, vectors, optionals, nested structs: they all hash correctly. No manual enumeration required.

Automatic hashing is actually one of the motivating examples in P2996 itself, listed as “member-wise hash_append.” The proposal authors clearly saw this use case coming. If you want to take a look at some other projects leveraging reflection you can take a look at mirror_bridge for automatic binding generation and simdjson for reflection-based JSON parsing and serialization.

As Munger warned in one of my favorite talks: “To a man with a hammer, everything looks like a nail.” At least compile-time reflection is a really cool hammer.

How It Works: Reflection at Compile Time

The magic happens with two new C++26 features working together:

1. nonstatic_data_members_of(^^T): Returns reflections of all data members
2. template for: Iterates over reflections at compile time (P1306 expansion statements)

template<typename Policy, Reflectable T>
std::size_t hash_impl(const T& value) noexcept {
    std::size_t result = 0;

    // template for: compile-time iteration over all members
    template for (constexpr auto member :
        std::meta::nonstatic_data_members_of(^^T, std::meta::access_context::unchecked()))
    {
        // value.[:member:] splices the reflection to access the actual member
        result = Policy::combine(result, hash_impl<Policy>(value.[:member:]));
    }

    return result;
}

Let’s break down the syntax:

• ^^T: The reflection operator. Returns a compile-time handle to type T’s metadata.
• nonstatic_data_members_of(...): Returns a range of reflections, one per data member.
• template for: Like a regular for, but unrolls at compile time. Each iteration is a separate instantiation.
• value.[:member:]: The splice operator. Converts a reflection back into code (in this case, member access).

What About Existing Solutions?

Fair question: do we really need C++26 reflection for this? There are existing approaches:

Boost.Describe: Requires annotating each struct with a macro:

struct Point { int x, y; };
BOOST_DESCRIBE_STRUCT(Point, (), (x, y))  // Manual member list

Works well, but you must remember to update the macro when adding members. Miss one, and you get silent bugs.

Cista: Requires a cista_members() function in each type:

struct Point {
    int x, y;
    auto cista_members() { return std::tie(x, y); }  // Manual
};

Same issue: manual enumeration that can drift out of sync.

Abseil Hash: Requires a friend function:

struct Point {
    int x, y;
    template<typename H>
    friend H AbslHashValue(H h, const Point& p) {
        return H::combine(std::move(h), p.x, p.y);  // Manual
    }
};

The pattern is clear: all existing solutions require manual member enumeration. You’re still writing boilerplate, just in a different form. Add a member, forget to update the hash, get subtle bugs.

mirror_hash is different. With C++26 reflection, the compiler provides the member list. There’s nothing to keep in sync:

struct Point { int x, y, z; };  // Add z, hash automatically includes it
auto h = mirror_hash::hash(Point{1, 2, 3});  // Just works

This is the fundamental advantage: true automatic generation with zero annotation overhead.

The Key Insight: Hash Only What You Use

One concern with automatic hashing: “Won’t this generate code for every type in my program?”

No. C++ templates are lazy. Hash functions are only instantiated when you actually use them:

struct NeverHashed {
    std::string name;
    std::vector<int> data;
};

struct ActuallyHashed {
    int id;
    double value;
};

int main() {
    // This instantiates hash code for ActuallyHashed only
    std::unordered_set<ActuallyHashed, mirror_hash::hasher<>> set;

    // NeverHashed gets no hash code generated
    NeverHashed unused;
}

The compiler only generates hash_impl<Policy, ActuallyHashed>. The NeverHashed struct incurs zero overhead because we never hash it.

This is the beauty of C++ templates: you don’t pay for what you don’t use. Reflection extends this principle: metadata is queried at compile time, and only for types that actually need it. See lazy_instantiation in test_mirror_hash.cpp for the test that verifies this behavior.

Handling Non-Trivially Copyable Types

A critical design decision in any hashing library: how do you handle types like std::string, std::vector, or structs containing them?

mirror_hash handles this through concept-based dispatch:

// Non-trivially copyable types get per-member hashing
template<typename T>
concept Reflectable = std::is_class_v<T> &&
    !StringLike<T> && !Container<T> && !Optional<T> && !Variant<T>;

// Strings hash their contents, not their internal pointers
template<typename Policy, StringLike T>
std::size_t hash_impl(const T& value) noexcept {
    return std::hash<T>{}(value);
}

// Containers iterate over elements
template<typename Policy, Container T>
std::size_t hash_impl(const T& value) noexcept {
    std::size_t result = hash_impl<Policy>(value.size());
    for (const auto& elem : value) {
        result = Policy::combine(result, hash_impl<Policy>(elem));
    }
    return result;
}

When you hash a struct containing a std::string:

struct Person {
    std::string name;  // Non-trivially copyable!
    int age;
};

mirror_hash recursively hashes each member. For name, it hashes the string contents. For age, it hashes the integer directly. This is safe and correct for complex types.

The Fast Path: Trivially Copyable Types

For simple structs like Point, we can do much better. If all members are trivially copyable (ints, floats, no pointers), we can hash the entire struct as raw bytes:

// Check if all members are trivially copyable using template for
template<typename T>
consteval bool all_members_trivially_copyable() {
    template for (constexpr auto member :
        std::meta::nonstatic_data_members_of(^^T, std::meta::access_context::unchecked()))
    {
        // [:type_of(member):] splices the member's type
        if (!std::is_trivially_copyable_v<[:std::meta::type_of(member):]>) {
            return false;
        }
    }
    return true;
}

template<typename Policy, Reflectable T>
std::size_t hash_impl(const T& value) noexcept {
    // Fast path: if all members are trivially copyable, hash raw bytes
    if constexpr (std::is_trivially_copyable_v<T> && all_members_trivially_copyable<T>()) {
        return hash_bytes_fixed<Policy, sizeof(T)>(&value);
    }

    // Slow path: iterate over members with template for
    std::size_t result = 0;
    template for (constexpr auto member : std::meta::nonstatic_data_members_of(^^T)) {
        result = Policy::combine(result, hash_impl<Policy>(value.[:member:]));
    }
    return result;
}

This compile-time optimization means a struct { int x, y, z; } gets hashed as a single 12-byte block, not three separate hash operations combined.

Under the Hood: The Byte Hashing Layer

This library has two distinct parts:

1. The reflection layer (novel): Automatically discovers struct members at compile time
2. The byte hashing layer (borrowed): Converts bytes to hash values using proven algorithms

Disclaimer: I’m not a cryptography expert. The byte hashing in mirror_hash comes from people who actually know what they’re doing. I make no cryptographic claims. For hash tables and checksums, this should be fine. For security-sensitive applications, please use a proper cryptographic hash.

The byte hashing is built on:

• rapidhash by Nicolas De Carli: What mirror_hash uses under the hood
• wyhash by Wang Yi: The foundation that rapidhash builds on
• GxHash by ogxd: Inspiration for the ARM64 AES optimization

Note on architecture: The reflection layer and byte hashing layer are completely independent. The reflection machinery discovers struct members and serializes them; the byte hasher converts those bytes to a hash value. You could swap rapidhash for xxHash, CityHash, or even SHA-256 if you needed different properties (portability, cryptographic strength, etc.). The AES optimization is just one choice we made for ARM64 performance - it’s not fundamental to the approach. The main contribution here is the integration layer: using C++26 reflection to automatically feed your struct’s bytes into these proven algorithms.

Using a different hash function: mirror_hash uses a policy-based design. You can plug in any hash function by defining a policy with mix and combine methods:

// Define a custom policy wrapping your preferred hash
struct my_xxhash_policy {
    static constexpr std::size_t mix(std::size_t k) noexcept {
        // Your finalization logic (e.g., XXH3_64bits avalanche)
        k ^= k >> 33;
        k *= 0xff51afd7ed558ccdULL;
        k ^= k >> 33;
        return k;
    }

    static constexpr std::size_t combine(std::size_t seed, std::size_t value) noexcept {
        // Your combining logic
        return seed ^ (value + 0x9e3779b9 + (seed << 6) + (seed >> 2));
    }
};

// Use it with any struct
struct Point { int x, y; };
auto h = mirror_hash::hash<my_xxhash_policy>(Point{1, 2});

// Or with containers
std::unordered_set<Point, mirror_hash::hasher<my_xxhash_policy>> points;

mirror_hash ships with several built-in policies: mirror_hash_policy (default, with AES acceleration on ARM64), folly_policy, wyhash_policy, murmur3_policy, xxhash3_policy, fnv1a_policy, and aes_policy. For bulk byte hashing, you can also specialize hash_bytes<YourPolicy> to use your preferred algorithm for raw memory.

The Core Mixing Primitive:

This is the one thing I didn’t touch. It’s the heart of rapidhash/wyhash:

inline void mum(uint64_t* A, uint64_t* B) noexcept {
    __uint128_t r = static_cast<__uint128_t>(*A) * (*B);
    *A = static_cast<uint64_t>(r);       // Low 64 bits
    *B = static_cast<uint64_t>(r >> 64); // High 64 bits
}

inline uint64_t mix(uint64_t A, uint64_t B) noexcept {
    mum(&A, &B);
    return A ^ B;
}

A 64×64→128 bit multiply has excellent avalanche properties: each input bit affects many output bits. The XOR of both 64-bit halves is crucial - it ensures entropy from the high bits (which contain information about large-magnitude products) mixes with the low bits (which preserve fine-grained patterns). Without this recombination, you’d lose half the information. This is well-studied math. I just use it.

Per 16 bytes of mixing: AES uses fewer instructions and cycles than 128-bit multiply. On Apple Silicon, AESE+AESMC fuse into a single ~2-cycle operation.

ARM64 with Hardware AES

On ARM64 processors with AES crypto extensions (Apple Silicon, AWS Graviton), mirror_hash uses a hybrid strategy:

Throughput across input sizes. Small inputs (8-16B) have ~22% overhead from dispatch logic, while 24-32B is roughly even. From 33-128B, mirror_hash wins ~93% of sizes with ~20% average speedup. Above 128B, 8-way AES kicks in (67-146% faster, with 100%+ at 512B and above).

Why is AES faster for medium inputs? ARM64’s AESE+AESMC instructions can mix 16 bytes in ~2 cycles using dedicated silicon. By comparison, the 128-bit multiply at the heart of rapidhash has data dependencies that limit throughput - each multiply must wait for the previous one. AES operations are independent, so we can run 4 or 8 of them in parallel on separate data lanes while the CPU’s execution units stay busy.

Why not use AES for everything? AES has setup overhead (loading keys, initializing state vectors) that dominates when you’re only hashing 8 bytes. For tiny inputs, the dispatch logic to choose between code paths adds overhead - rapidhashNano is fast, but calling it through mirror_hash’s size-checking dispatch costs ~22% at 8-16 bytes.

The hybrid approach:

• 0-32 bytes: rapidhashNano (AES setup overhead not amortized for tiny inputs)
• 33-128 bytes: Single-state AES with 32-byte unrolling and overlapping read (~20% faster than rapidhash on average, wins 93% of sizes)
• 129-512B: 8-way unrolled AES (67-100% faster as parallelism amortizes)
• 512B-8KB: Full 8-way AES acceleration (100-146% faster than rapidhash)
• >8KB: rapidhash (memory bandwidth dominates)

The 33-128 byte range uses an optimized single-state approach. Instead of 4-way parallel processing (which has setup overhead), mirror_hash v2.1 uses 32-byte unrolled processing with a single accumulator.

For handling the 1-15 byte remainder after aligned blocks, mirror_hash uses an overlapping read: instead of copying the remaining bytes to a zeroed buffer, it reads the last 16 bytes of the input—which may overlap with already-processed data:

// Traditional approach (slower):
alignas(16) uint8_t buf[16] = {0};  // stack alloc + zero init
memcpy(buf, ptr, remainder_len);     // copy 1-15 bytes
buf[15] = remainder_len;             // encode length

// Overlapping read (faster):
uint8x16_t data = vld1q_u8(end - 16);           // single 16-byte load
data = veorq_u8(data, vdupq_n_u8(remainder_len)); // XOR length into every byte

The XOR with remainder length ensures different-length inputs hash differently, even when they share the overlapping bytes. Benchmarking shows this is 2x faster than the memcpy approach for handling partial blocks—the stack allocation, zero-initialization, and variable-length copy add significant overhead compared to a single 16-byte load. Measured results:

mirror_hash wins consistently across the 33-128 byte range regardless of alignment.

mirror_hash speedup at key sizes. Green = mirror_hash wins, Blue = rapidhash wins. Small inputs (8-16B) show dispatch overhead. From 48B onward, AES acceleration provides consistent wins.

Left: Small inputs show dispatch overhead at 8-16B, roughly even at 24-32B. Right: Large inputs (128B-8KB) show AES acceleration dominating with 18-146% speedups.

Why mirror_hash Beats GxHash at Large Inputs

Wait, mirror_hash beats GxHash by 23% at 8KB? They both use hardware AES. What’s going on?

The difference comes down to instruction count per compression step. Looking at the actual assembly:

GxHash’s fast compression (4 instructions):

movi  v2.2d, #0           ; create zero vector
aese  v0.16b, v2.16b      ; AESE with zero key
aesmc v0.16b, v0.16b      ; MixColumns
eor   v0.16b, v0.16b, v1  ; XOR with input b

mirror_hash’s fast compression (2 instructions):

aese  v0.16b, v1.16b      ; AESE with b as key
aesmc v0.16b, v0.16b      ; MixColumns

The key insight: ARM64’s AESE instruction incorporates the key XOR into the operation. GxHash does AESE(a, 0) then XOR(result, b) as separate steps. mirror_hash does AESE(a, b) directly, saving two instructions per compression.

At 8KB, we do 64 iterations of 128-byte blocks, with 7 fast compressions per iteration:

• GxHash: 64 × 7 × 4 = 1792 instructions
• mirror_hash: 64 × 7 × 2 = 896 instructions

That’s 50% fewer instructions for the fast compression step alone.

There’s also a secondary factor: key loading. GxHash loads keys inside its compression function on every call. mirror_hash loads keys once before the loop and keeps them in NEON registers:

// GxHash: loads keys every time
static inline state compress(state a, state b) {
    uint8x16_t k1 = vld1q_u32(keys_1);  // Load from memory
    uint8x16_t k2 = vld1q_u32(keys_2);  // Load from memory
    // ... use k1, k2
}

// mirror_hash: keys loaded once, passed as parameters
uint8x16_t k1 = vld1q_u8(KEY1);  // Once before loop
uint8x16_t k2 = vld1q_u8(KEY2);
while (len >= 128) {
    hash = compress_full(hash, v0, k1, k2);  // k1, k2 in registers
}

For 8KB, that’s 64 × 2 = 128 extra memory loads avoided.

Measured results (ARM64, native Docker):

• GxHash-style: 96.84 ns
• mirror_hash-style: 79.08 ns
• Speedup: +22.5%

The full profiling is in profiling/aes_deep_analysis.cpp.

See benchmarks/gxhash_comparison.cpp for the full benchmark. All measurements from an M3 Max MacBook Pro.

Quality Validation: SMHasher

Quality matters as much as speed. A fast hash that produces collisions is useless.

mirror_hash passes the full SMHasher test suite - the canonical hash function quality benchmark. This isn’t a subset or simplified version; it’s the real thing, taking 30+ minutes to run all tests:

cd smhasher_upstream/build
./SMHasher mirror_hash_unified

Key test results:

The hash is integrated directly into SMHasher’s source tree (smhasher_upstream/), so you can run the tests yourself.

Benchmarks

How fast is the reflection-based approach? Here are measured times on ARM64 (M3 Max, Clang 21, -O3):

The time scales with the actual work required:

• String hashing depends on string length (though SSO, or Small String Optimization, helps for short strings by storing them inline)
• Container hashing iterates over all elements; there’s no shortcut
• Member count adds overhead for the combine operations

This isn’t “overhead” in the sense of wasted work. It’s the inherent cost of correctly hashing dynamic data. A hand-written hash function would have the same cost. The value of mirror_hash is that you don’t have to write it yourself.

Run the benchmark yourself:

./build/benchmark

The Catch: You Need a Special Compiler (for now)

C++26 reflection isn’t in any released compiler yet. You need Bloomberg’s clang-p2996 branch:

# Compile flags
clang++ -std=c++2c -freflection -freflection-latest mycode.cpp

It’s experimental. It might break. But it’s a glimpse of C++’s future, and that future involves a lot less boilerplate.

When NOT to Use This

mirror_hash isn’t always the right choice:

• Cryptographic hashing: Use SHA-256, BLAKE3, etc. mirror_hash is for hash tables, not security.
• Custom hash semantics: If only some fields should contribute to the hash (e.g., skip cached values), you need manual control.
• Cross-platform determinism: Hash values may differ between platforms or compiler versions. Don’t persist them.
• Pre-C++26 codebases: Requires experimental compiler support that may not be production-ready.

For these cases, stick with hand-written std::hash specializations or established libraries.

Try It Out

git clone https://github.com/FranciscoThiesen/mirror_hash
cd mirror_hash
./start_dev_container.sh  # Uses Docker with clang-p2996
./build.sh
./run_tests.sh

Conclusion

What started as “let’s avoid writing std::hash boilerplate” turned into a journey through:

1. C++26 reflection and template for
2. Trivially copyable optimizations
3. 128-bit multiply mixing (rapidhash)
4. Hardware AES acceleration
5. Memory bandwidth analysis

The days of manually writing std::hash specializations are numbered. C++26 reflection gives us the tools to generate them automatically, and with the right platform-specific optimizations, performance can be excellent too.

For years, we’ve written code that the compiler could infer. We’ve manually enumerated members that the compiler already knows about. P2996 finally bridges that gap.

The future of C++ is less boilerplate and more automation. And I, for one, can’t wait.

mirror_hash is MIT licensed. The underlying hash algorithms (wyhash, rapidhash, xxHash) have their own licenses. Please check their respective repositories.

Acknowledgments

Thanks to Wyatt Childers, Peter Dimov, Dan Katz, Barry Revzin, Andrew Sutton, Faisal Vali, and Daveed Vandevoorde for authoring and championing P2996, the reflection proposal that makes this all possible.

Special thanks to Dan Katz for maintaining the clang-p2996 branch. Without a working compiler, this would all be theoretical.

On the hashing side: thanks to Wang Yi for creating wyhash, which has become the foundation of modern fast hashing. Thanks to Nicolas De Carli for rapidhash, the fastest portable hash function I’ve tested. Thanks to ogxd for GxHash, which showed me how to use hardware AES for hashing and whose 8-way unrolling strategy mirror_hash adapts. And thanks to Yann Collet for xxHash, which has been battle-tested for over a decade and set the standard for what a high-quality hash function should be.

References

• P2996R13 - Reflection for C++26: The main reflection proposal
• P1306R5 - Expansion Statements: The template for feature
• Bloomberg clang-p2996: Experimental compiler with reflection support
• Trip Report: June 2025 ISO C++ Meeting: When reflection was voted into C++26
• SMHasher: The canonical hash quality test suite
• rapidhash: The hash algorithm that mirror_hash builds upon
• wyhash: The foundation of modern fast hashing
• GxHash: Hardware AES-accelerated hashing that inspired the ARM64 optimization

The Mandelbrot set, rendered identically by Python, Lua, and JavaScript calling the same C++ engine

The Benchmark

PyPy. LuaJIT. V8. These are serious JIT compilers with years of optimization work behind them. Let’s see how they compare.

800×600 Mandelbrot, 256 max iterations. Lower is better.

PYTHON
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Pure CPython:    2.51s  ████████████████████████████████████████
Pure PyPy:       0.14s  ██▎
C++ Binding:     0.06s  █

LUA
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Pure Lua 5.4:    0.77s  █████████████
Pure LuaJIT:     0.24s  ████
C++ Binding:     0.07s  █▏

JAVASCRIPT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Pure V8:         0.10s  █▌
C++ Binding:     0.06s  █

V8 is a serious piece of engineering: speculative optimization, inline caching, hidden classes. And we can still beat it.

How It Works

If you’re not familiar with C++26 reflection, check out my previous post on Mirror Bridge for the fundamentals.

The short version: C++26 reflection lets you iterate over struct members at compile time:

template for (constexpr auto member : std::meta::nonstatic_data_members_of(^^T)) {
    auto& value = obj.[:member:];  // splice member directly into code
    // generate binding for this member...
}

The [:member:] splice compiles to a direct memory offset, exactly like hand-written obj.width. No string lookup, no virtual dispatch.

The entire binding for Mandelbrot:

MIRROR_BRIDGE_MODULE(mandelbrot,
    mirror_bridge::bind_class<Mandelbrot>(m, "Mandelbrot");
)

One line. Every constructor, method, and property discovered and bound automatically.

Why Was C++ Losing to V8?

Early benchmarks showed something unexpected: the C++ binding was running at 0.7× V8’s speed. What was going on?

The culprit wasn’t the computation. It was the data transfer.

render_rgb() returns 1.44 million bytes (800×600×3). A naive binding converts element-by-element:

// The bottleneck: 1.44 million calls to napi_set_element
for (size_t i = 0; i < data.size(); i++) {
    napi_set_element(env, array, i, to_js(data[i]));
}

The fix: detect byte containers and use bulk transfer:

template<ByteContainer T>
napi_value to_javascript(napi_env env, const T& container) {
    void* buffer_data;
    napi_create_arraybuffer(env, container.size(), &buffer_data, &buffer);
    std::memcpy(buffer_data, container.data(), container.size());  // Single copy
    return typed_array;  // Returns Uint8Array
}

This single change took the JavaScript binding from 0.7× to 1.5× V8’s speed. The C++ computation was always winning; naive data transfer was losing it all back.

Mirror Bridge now detects ByteContainer types (contiguous ranges of bytes) and uses bulk transfers across all three language bindings.

vs. Existing Solutions

Why not just use pybind11?

You absolutely can. pybind11 is mature, well-documented, and battle-tested.

But if you’re binding the same types to multiple languages, or you’re tired of keeping binding declarations in sync with your headers, reflection gives you a third option: declare nothing, discover everything.

What About C++26?

“C++26 isn’t in compilers yet!”

True. P2996 was voted into C++26 at the Sofia meeting in June 2025, so the standard is locked. But mainstream compiler support is still catching up.

Mirror Bridge uses Bloomberg’s experimental Clang fork. The dev container includes everything pre-configured:

./start_dev_container.sh  # Reflection-enabled Clang, ready to go

This is what idiomatic C++ binding code will look like once compilers catch up.

Try It

git clone https://github.com/FranciscoThiesen/mirror_bridge
cd mirror_bridge
./start_dev_container.sh

cd examples/mandelbrot-demo
bash build_mandelbrot_full.sh

You’ll see:

• Benchmark comparisons across all runtimes
• Generated animation frames (the GIF above)
• The full binding code (it really is one line per language)

The Code

C++ (the only implementation):

struct Mandelbrot {
    int width, height, max_iter;
    double x_min, x_max, y_min, y_max;

    void set_viewport(double xmin, double xmax, double ymin, double ymax) {
        x_min = xmin; x_max = xmax; y_min = ymin; y_max = ymax;
    }

    std::vector<uint8_t> render_rgb() const {
        std::vector<uint8_t> pixels(width * height * 3);
        for (int py = 0; py < height; py++) {
            for (int px = 0; px < width; px++) {
                double x = x_min + (x_max - x_min) * px / width;
                double y = y_min + (y_max - y_min) * py / height;
                double t = escape_time(x, y);
                // ... color mapping ...
            }
        }
        return pixels;
    }

private:
    double escape_time(double cr, double ci) const {
        double zr = 0, zi = 0;
        int iter = 0;
        while (zr*zr + zi*zi <= 4.0 && iter < max_iter) {
            double temp = zr*zr - zi*zi + cr;
            zi = 2*zr*zi + ci;
            zr = temp;
            iter++;
        }
        return iter;  // + smooth coloring in real code
    }
};

Python:

m = mandelbrot.Mandelbrot(800, 600, 256)
m.set_viewport(-0.75, -0.73, 0.1, 0.12)
pixels = m.render_rgb()  # bytes, 39× faster than pure Python

Lua:

local m = mandelbrot.Mandelbrot(800, 600, 256)
m:set_viewport(-0.75, -0.73, 0.1, 0.12)
local pixels = m:render_rgb()  -- 10× faster than pure Lua

JavaScript:

const m = new mandelbrot.Mandelbrot(800, 600, 256);
m.set_viewport(-0.75, -0.73, 0.1, 0.12);
const pixels = m.render_rgb();  // Uint8Array, 1.5× faster than V8

Same computation. Same pixels. Three languages calling one C++ implementation.

What’s Next

The same reflection infrastructure that generates language bindings can power:

• Serialization: JSON, MessagePack, Protobuf from struct definitions
• RPC: gRPC service stubs generated from C++ classes
• GUI: Automatic property editors for your types
• ORM: Database schemas derived from struct layouts

One new C++ language feature, many interesting applications!

Benchmark methodology: Each implementation renders the same viewport 10 times; reported time is the median. “Pure” implementations use idiomatic code for each language (numpy-style vectorization for Python, standard loops for Lua/JS). Hardware: Apple M3 Max, single-threaded. Full benchmark code in the repo.

Mirror Bridge on GitHub

But there’s this one function. It shows up in every profile. It’s eating 80% of your runtime. You know it would be faster in C++.

The traditional answer? Rewrite it in C++, then spend sometime writing pybind11 boilerplate to call it from Python. Or just… don’t bother.

Mirror Bridge is a third option: write C++, run one command, done.

The Setup

Let’s say you have a simple operation - a dot product:

// vec3.hpp
struct Vec3 {
    double x, y, z;

    Vec3(double x, double y, double z) : x(x), y(y), z(z) {}

    double dot(const Vec3& other) const {
        return x * other.x + y * other.y + z * other.z;
    }

    // Compute the magnitude (norm) of the vector
    double length() const {
        return std::sqrt(x*x + y*y + z*z);
    }
};

To use this from Python:

./mirror_bridge_auto src/ --module vec3 -o .

That’s it. No binding code. Mirror Bridge uses C++26 reflection to discover your classes, methods, and fields automatically.

import vec3

a = vec3.Vec3(1, 2, 3)
b = vec3.Vec3(4, 5, 6)
print(a.dot(b))  # 32.0

The Naive Benchmark (And Why It’s Misleading)

Let’s call dot() a million times:

for _ in range(1_000_000):
    a.dot(b)

Results (M3 Max MacBook Pro):

Python class: 0.11s
C++ via Mirror Bridge: 0.04s
Speedup: 2.9x

A ~3x speedup. Not bad, but not eye-popping. What’s going on?

This benchmark can be somewhat misleading

Each call from Python to C++ pays a toll - argument conversion, language boundary crossing, result conversion. For a trivial operation like dot() (3 multiplies, 2 adds), that toll dominates the actual work.

This is like benchmarking a Ferrari by measuring how fast it can start and stop at every intersection. You’re measuring overhead, not speed.

Dissecting the Cross-Language Barrier

What actually happens when Python calls a C++ function? Let’s trace through a single a.dot(b) call:

1. Method lookup. Python sees a.dot and searches for the dot attribute. It checks a.__dict__, then type(a).__dict__, walking up the MRO (Method Resolution Order). For our bound C++ class, this eventually finds a descriptor that wraps the C++ method.

2. Argument boxing. Python passes b as a PyObject* - a pointer to a heap-allocated structure containing a reference count, type pointer, and the actual data. The binding layer (nanobind, in Mirror Bridge’s case) must extract the underlying C++ Vec3 from this Python wrapper.

3. Type checking. Is b actually a Vec3? The binding layer verifies this at runtime. In pure C++, the compiler guarantees types at compile time - no runtime check needed.

4. GIL management. The Global Interpreter Lock might need to be considered. For simple numeric operations we keep it held, but for longer operations you’d release it to allow other Python threads to run.

5. The actual call. Finally, we call the C++ dot() method. This is the fast part - a few nanoseconds for 3 multiplies and 2 adds.

6. Result conversion. The C++ double result must be wrapped in a Python float object - another heap allocation, reference count initialization, and type pointer setup.

7. Return. Python receives a PyObject* pointing to the new float.

For a function that does microseconds of work, this overhead is negligible. For a function that does nanoseconds of work - like our dot() - the overhead dominates. You’re spending more time crossing the border than doing actual computation.

Why Is C++ Faster in the First Place?

Even setting aside the cross-language overhead, why is C++ inherently faster for the same operation? Let’s look at what each language actually does for dot():

Python’s journey:

def dot(self, other):
    return self.x*other.x + self.y*other.y + self.z*other.z

Each attribute access (self.x) involves:

• Dictionary lookup in self.__dict__
• If not found, search the class hierarchy
• Return a Python float object (heap-allocated, reference-counted)

Each multiplication:

• Check types of both operands at runtime
• Dispatch to the appropriate __mul__ implementation
• Allocate a new Python float for the result

Each addition: same story. We can see this by looking at the Python bytecode:

# Python bytecode for Vec3.dot() - run: python3 -c "import dis; dis.dis(Vec3.dot)"
  0 LOAD_FAST      0 (self)
  2 LOAD_ATTR      0 (x)      # dict lookup for self.x
  4 LOAD_FAST      1 (other)
  6 LOAD_ATTR      0 (x)      # dict lookup for other.x
  8 BINARY_MULTIPLY           # type check, dispatch, allocate result
 10 LOAD_FAST      0 (self)
 12 LOAD_ATTR      1 (y)      # dict lookup for self.y
 14 LOAD_FAST      1 (other)
 16 LOAD_ATTR      1 (y)      # dict lookup for other.y
 18 BINARY_MULTIPLY           # type check, dispatch, allocate result
 20 BINARY_ADD                # type check, dispatch, allocate result
 22 LOAD_FAST      0 (self)
 24 LOAD_ATTR      2 (z)      # dict lookup for self.z
 26 LOAD_FAST      1 (other)
 28 LOAD_ATTR      2 (z)      # dict lookup for other.z
 30 BINARY_MULTIPLY           # type check, dispatch, allocate result
 32 BINARY_ADD                # type check, dispatch, allocate result
 34 RETURN_VALUE

That’s 18 bytecode instructions, each of which expands to many machine instructions. The LOAD_ATTR operations involve hash table lookups. The BINARY_* operations involve type checking and dynamic dispatch. By the end, we’ve done 6 attribute lookups, 5 arithmetic operations (each with type checks), and allocated several intermediate float objects.

C++’s journey:

double dot(const Vec3& other) const {
    return x * other.x + y * other.y + z * other.z;
}

The compiler knows at compile time:

• x, y, z are double values at fixed offsets from this
• other.x, other.y, other.z are at fixed offsets from &other
• All operations are double * double and double + double

Here’s the actual generated assembly (clang 18, -O3):

call_dot(Vec3 const&, Vec3 const&):
  movsd xmm1, qword ptr [rdi]       ; load a.x
  movsd xmm0, qword ptr [rdi + 8]   ; load a.y
  mulsd xmm0, qword ptr [rsi + 8]   ; a.y * b.y
  mulsd xmm1, qword ptr [rsi]       ; a.x * b.x
  addsd xmm1, xmm0                  ; (a.x*b.x) + (a.y*b.y)
  movsd xmm0, qword ptr [rdi + 16]  ; load a.z
  mulsd xmm0, qword ptr [rsi + 16]  ; a.z * b.z
  addsd xmm0, xmm1                  ; add all three
  ret                                ; result in xmm0

That’s it. Four memory loads (some folded into mulsd), three multiplies, two adds, one return. No allocations. No type checks. No dictionary lookups. The entire function is 9 instructions.

This is why the “naive” benchmark shows only 3x speedup instead of 100x: Python’s overhead for calling a function (even a Python function) is substantial, so replacing the implementation with C++ helps less than you’d expect. The win comes when you stop crossing the boundary repeatedly.

The Real Benchmark: Surgical Optimization

In practice, you don’t call C++ a million times from Python. You identify a hot loop and move the entire loop to C++.

Imagine you have this in your Python codebase:

def hot_loop(n):
    """This function showed up in your profiler."""
    direction = Vec3(1, 1, 1)
    dir_len = direction.length()  # Magnitude (norm) of direction vector
    total = 0.0
    for i in range(n):
        v = Vec3(i * 0.1, i * 0.2, i * 0.3)
        total += v.dot(direction) / dir_len
    return total

It’s called from dozens of places. The Vec3 class is used throughout your codebase. You don’t want to rewrite everything - you just want this loop to go fast.

So you write the C++ version:

// Add to vec3.hpp
struct Vec3 {
    // ... existing code ...

    static double hot_loop(int n) {
        Vec3 direction(1, 1, 1);
        double dir_len = direction.length();
        double total = 0.0;
        for (int i = 0; i < n; ++i) {
            Vec3 v(i * 0.1, i * 0.2, i * 0.3);
            total += v.dot(direction) / dir_len;
        }
        return total;
    }
};

Rebuild: ./mirror_bridge_auto src/ --module vec3 -o . --force

Now benchmark:

# Python version
result = hot_loop(1_000_000)

# C++ version - ONE call, all work happens in C++
result = vec3.Vec3.hot_loop(1_000_000)

Results (M3 Max MacBook Pro):

Python: 0.26s
C++:    0.004s
Speedup: 67x

That’s the real number. You pay the Python→C++ toll once. The loop runs at full native speed.

Why Not Just Rewrite Everything in C++?

Because you probably shouldn’t.

Python gives you:

• Rapid iteration (no compile step during development)
• A massive ecosystem (PyTorch, pandas, requests, FastAPI…)
• Readable glue code that connects everything
• Easy onboarding for new team members

The Pareto principle applies aggressively here. 80% of your runtime might come from 20% of your code. Often it’s even more skewed - a single hot loop can dominate everything.

Mirror Bridge lets you surgically replace just the hot 20% with C++, keeping the other 80% in Python. You get:

• Python’s ergonomics for the code that doesn’t need to be fast
• C++ performance for the code that does
• Zero binding boilerplate connecting them

The Magic: C++26 Reflection

Here’s where it gets interesting. How does Mirror Bridge discover your classes automatically?

The answer is C++26 static reflection (P2996) - a new language feature that lets code inspect itself at compile time.

When you run mirror_bridge_auto, it generates code that looks something like this:

// Auto-generated binding code (simplified)
#include "vec3.hpp"
#include <mirror_bridge.hpp>

MIRROR_BRIDGE_MODULE(vec3,
    mirror_bridge::bind_class<Vec3>(m, "Vec3");
)

The magic is in bind_class<Vec3>. Using reflection, Mirror Bridge can ask the compiler:

// What Mirror Bridge does internally
constexpr auto type_info = ^Vec3;  // "reflection operator" - get metadata about Vec3

// Get all members of Vec3
constexpr auto members = std::meta::members_of(type_info);

// Iterate over them AT COMPILE TIME
template for (constexpr auto member : members) {
    // What's the name of this member?
    constexpr auto name = std::meta::identifier_of(member);

    // Is it public?
    if constexpr (std::meta::is_public(member)) {

        // Is it a function?
        if constexpr (std::meta::is_function(member)) {
            // Bind it as a Python method
            cls.def(name, /* pointer to member function */);
        }

        // Is it a data member?
        else if constexpr (std::meta::is_nonstatic_data_member(member)) {
            // Bind it as a Python attribute
            cls.def_readwrite(name, /* pointer to member */);
        }
    }
}

The ^ operator (called the “reflection operator”) takes a type and returns a compile-time value representing that type’s metadata. From there, std::meta functions let you query everything about it: members, their types, their names, whether they’re public, static, const, etc.

This is fundamentally different from runtime reflection (like Java or C#). Everything happens at compile time:

• Zero runtime overhead - the reflection queries are resolved during compilation
• Full type safety - the compiler knows exact types, no casting or dynamic lookups
• Works with templates - you can reflect on template instantiations

Before P2996, generating Python bindings required either:

1. Manual listing (pybind11) - tedious and error-prone
2. Code parsing (SWIG) - fragile and limited
3. Macros (Boost.Python) - ugly and inflexible

Reflection gives us a fourth option: ask the compiler directly. It already knows everything about your types. Now we can access that knowledge programmatically.

The Comparison

For context, here’s what the traditional pybind11 approach requires:

#include <pybind11/pybind11.h>
#include "vec3.hpp"

PYBIND11_MODULE(vec3, m) {
    py::class_<Vec3>(m, "Vec3")
        .def(py::init<double, double, double>())
        .def_readwrite("x", &Vec3::x)
        .def_readwrite("y", &Vec3::y)
        .def_readwrite("z", &Vec3::z)
        .def("dot", &Vec3::dot)
        .def("length", &Vec3::length)
        .def_static("hot_loop", &Vec3::hot_loop);
}

Every single method needs to be manually listed. And when you add a new one? Update the Python bindings. Forgot one? Silent failure at runtime.

With Mirror Bridge: write C++, run command, done.

Getting Started

git clone https://github.com/FranciscoThiesen/mirror_bridge
cd mirror_bridge
./start_dev_container.sh  # Pre-built Docker image with clang-p2996

# Inside container - try the example from this post
cd /workspace/examples/blog_vec3
../../mirror_bridge_auto . --module vec3 -o .
python3 benchmark.py

The examples/blog_vec3 directory contains all the code from this post, ready to run.

The Docker image includes clang-p2996, Bloomberg’s experimental Clang fork that implements the reflection proposal. As P2996 moves toward standardization, expect this to land in mainline compilers.

The Bottom Line

The next time you’re staring at a Python profiler, wondering if it’s worth the hassle to optimize that hot loop in C++, the answer is: yes, and it should take less than five minutes.

Write the C++ version. Run mirror_bridge_auto. Replace the call. Ship it.

• Mirror Bridge on GitHub
• C++26 Reflection Proposal (P2996)
• clang-p2996

Acknowledgments

Mirror Bridge wouldn’t exist without the work of many others. Thanks to Wyatt Childers, Peter Dimov, Dan Katz, Barry Revzin, Andrew Sutton, Faisal Vali, and Daveed Vandevoorde for authoring and championing P2996. Special thanks to Dan Katz for maintaining the clang-p2996 branch that makes this all possible today.

Herb Sutter’s CppCon 2025 talk on reflection was also a motivating force for this work, making the case of a common language to rule them all, which motivate me to try to make it easier for other languages to call C++.

The idea of using reflection to generate Python bindings isn’t new - it was explored by others before, including in this ACCU 2025 talk. Mirror Bridge builds on these ideas and packages them into a tool you can use today.

Thankfully, a few JSON parsers have shown that we can process JSON at high speeds, reaching gigabytes per second¹².

However, producing and ingesting JSON data can remain a chore in C++. The programmer often needs to address potential errors such as unexpected content.

Often, the programmer only needs to map the content to and from a native C/C++ data structure. E.g., our JSON example might correspond to the following C++ structure:

struct kid {
    int age;
    std::string name;
    std::vector<std::string> toys;
};

Hence, we would often like to write simple code such as kid k; store_json(k, out) or kid k; load_json(k, in). Ideally, we would like this code to be fast and safe. That is, we would like to write and read our data structures at gigabytes per second. Further, we want proper validation especially since the JSON data might come from the Internet.

A library such as simdjson already allows elegant deserialization, e.g., we can make the following example work:

struct kid {
  int age;
  std::string name;
  std::vector<std::string> toys;
};

void demo() {
  auto json_str =
      R"({"age": 12, "name": "John", "toys": ["car", "ball"]})"_padded;
  simdjson::ondemand::parser parser;
  auto doc = parser.iterate(json_str);
  kid k = doc.get<kid>();
}

However, for the time being, it requires a bit of effort on the part of the programmer—as they need to write a custom function.

Similarly, going from the C++ structures to JSON can be made convenient, but typically only after the programmer has done a bit of work, writing custom code. E.g., in the popular JSON for Modern C++ (nlohmann/json) library, we need to provide glue functions:

void to_json(json& j, const person& p) {
    j = json{{"name", p.name}, {"address", p.address}, {"age", p.age}};
}

void from_json(const json& j, person& p) {
    j.at("name").get_to(p.name);
    j.at("address").get_to(p.address);
    j.at("age").get_to(p.age);
}

We know that this extra effort (writing data-structure aware code) is unnecessary because other programming languages (Java, C#, Zig, Rust, Python, etc.) allow us to ‘magically’ serialize and deserialize with almost no specialized code.

One key missing feature in C++ is sufficiently powerful reflection. Reflection in programming languages refers to a mechanism that allows code to introspect its own structure. That is, if you cannot conveniently tell C++ that if a class has a std::string name attribute, then you should automatically search for a string value matching the key name in the JSON.

Thankfully, C++ is soon getting reflection in C++26³. And it is getting powerful reflection: reflective metaprogramming. That is, future versions of C++ will allow us to solve the serialization and deserialization problem we described at compile time: a software library can automate the production and consumption of JSON to and from a native data structure. Such a feature will simplify the life of the C++ programmer. Furthermore, because it can be done automatically as part of well tested library at compile time, it can generate fast and safe code.

Herb Sutter wrote about this development:

This is huge, because reflection (including generation) will be by far the most impactful feature C++ has ever added since C++98, and it will dominate the next decade and more of C++ usage.

Though many programming languages have reflection, the reflective metaprogramming provided by the upcoming C++ standard is unique to our knowledge. Some programming languages have long had powerful reflection capabilities, but they are mostly a runtime feature: they do not allow the equivalent of generating code. Other programming languages allow compile-time logic generation but they do not always allow optimal performance. We expect that the C++ approach might be especially appropriate for high performance.

Though current C++ compilers do not yet support reflection, we have access to prototypical compilers. In particular, engineers from Bloomberg maintain a fork of LLVM. Though such an implementation should not be used in production and is subject to bugs and other limitations, it should be sufficient to test the performance: how fast can serialization-based JSON processing be in C++? Importantly, we are not immediately concerned with compilation speed: the Bloomberg fork is purposefully suboptimal in this respect.

To test out this new C++ feature, we wrote a prototype that can serialize and deserialize data structures to and from JSON strings automatically. Given an instance of kid, we can convert it to a JSON string without any effort, the compile-time reflection does the work:

  kid k{12, "John", {"car", "ball"}};
  std::print("My JSON is {}\n", simdjson::json_builder::to_json_string(k));

Benchmark Results with Speed-up

Automatically converting your C++ data types into JSON strings is convenient. But is it fast? To find out, we have used 2 instances for benchmarking, an “Artificial instance” that was obtained using the JSON Generator Website and the other one is the twitter.json file that is used by many other serialization libraries for benchmarking.

We test on two systems (Apple and Intel/Linux) with the experimental LLVM Bloomberg compiler.

M3 MAX Macbook Pro:

Intel Ice Lake:

Our benchmark showed that we are roughly 20× faster than nlohmann/json. This was achieved by combining the new reflection capabilities with some bit twiddling tricks and a string_builder class to help minimize the overhead of memory allocations.

Importantly, our implementation requires little code. The C++26 reflection capabilities do all the hard work. In our benchmarks, we further compare against hand-written functions as well as an existing C++ reflection library (reflect-cpp). Hand-written code can be slightly faster than our reflection-based code, but the difference is small (10% to 20%). We can be twice as fast as reflect-cpp although it is also a very fast library.

Conclusion

One results suggest that C++26 with reflection is a powerful tool that should allow C++ programmers to easily serialize and deserialize data structures at gigabytes per second. In the near future, the simdjson library will adopt reflection for both serialization and deserialization. Indeed, we expect that this will help users get high performance in some important cases with little effort.

Credit

Joint work with the amazing Daniel Lemire!

We are grateful to @the-moisrex for teaching us about tag dispatching and initiating its adoption in the simdson library.

Appendix: complete code example

struct kid {
  int age;
  std::string name;
  std::vector<std::string> toys;
};

/**
 * The following function would print:
 *
 *   I am 12 years old
 *   I have a car
 *   I have a ball
 *   My name is John
 *   My JSON is {"age":12,"name":"John","toys":["car","ball"]}
 *
 */
void demo() {
  simdjson::padded_string json_str =
      R"({"age": 12, "name": "John", "toys": ["car", "ball"]})"_padded;
  simdjson::ondemand::parser parser;
  auto doc = parser.iterate(json_str);
  kid k = doc.get<kid>();
  std::print("I am {} years old\n", k.age);
  for (const auto &toy : k.toys) {
    std::print("I have a {}\n", toy);
  }
  std::print("My name is {}\n", k.name);

  std::print("My JSON is {}\n", simdjson::json_builder::to_json_string(k));
}

• Implemented a complex expected linear time algorithm for finding Minimum Spanning Tree.
• Found a bug in an implementation in a 13 years old paper.
• Code available at github

Context

It was the end of 2019 and I was searching for an interesting topic for my CS undergraduate final thesis. I was looking into randomized algorithms and was really surprised to find out that there was an expected linear time complexity algorithm for the Minimum Spanning Tree problem. The authors are Karger, Klein and Tarjan and from now on I’ll refer to it as \(KKT\), not to be confused with “Karush-Kuhn-Tucker”.

In my algorithms class and also during my studies for the ICPC I had only stumbled upon 3 different ways of solving the problems, with a complexity of \(O(m \cdot \log(n))\) where \(m\) is the number of edges and \(n\) is the number of vertices in the graph

• Borůvka
• Kruskal
• Prim

An algorithm with expected complexity of \(O(m + n)\) belongs to a complexity class that grows slower than the class offered by the classical algorithms listed above, so for graphs sufficiently large \(KKT\) algorithm should come in handy. At this point I was super curious to test the performance of it against the classical algorithms.

Let’s benchmark it!

Benchmarks are nice, but there was not going to be easy… As of early 2020, I couldn’t find a working implementation of the \(KKT\) algorithm that I could use for benchmarking purposes.

At this point I had 2 reasonable options:

1. Go find some other topic for my undergrad thesis.
2. Be brave and implement this not-so-trivial \(KKT\) algorithm and make a publicly available implementation. This can work as a thesis + satisfy my personal curiosity + hopefully contribute a working implementation to society.

As you have probably guessed (given the title of this post), I went for option 2.

When implementing a complex algorithm, how can we find out estimate the implementation complexity?

When we are dealing with a simple algorithm to implement, it is much easier to inspect every small detail of the implementation and become somewhat confident that the implementation actually matches the theoretical complexity. Even in those cases it is not unusual to find out situations where the implementation does not behave as expected, like in the Binary Search Bug.

For more complex algorithms, things get even trickier. My approach was to use the google benchmark project, that fortunately has a complexity “estimation” feature built-in. It was also super convenient to use. It is worth mentioning that this is only an estimate of the implementation complexity and not a guarantee. To see how I used it in the scope of my project, see my benchmarking file.

Hard bug

After completing thinking I had completed the implementation of \(KKT\). It was natural for me to test my implementation with a rich set of different graphs. I had ~3 months to complete the tests and write my thesis report and prepare my presentation.

But there was a catch! I was validating the \(KKT\) result against the minimum spanning trees produced by the other classical algorithms. When testing on graphs with > 1000 nodes, I got an error in about 1% of the instances, in which the solution discovered by \(KKT\) were around 1% worse than the solutions found by all the 3 classical algorithms.

It was something terribly hard to debug, because I couldn’t reproduce the issue with graphs of a smaller size. As someone who has made a lot of implementation mistakes in the past, my usual instict is to assume the error is in some implementation mistake I made. This reminds me of the time when Rafael Nadal played with a broken racket when he was 15, because he was so used to taking responsibility for his losses that the idea that the racket was broken didn’t even cross his mind.

After scrutinizing the code for a long time and adding A LOT of print statements, I started suspecting that the error might not be on me this time. How could that be?

Well, \(KKT\) leverages another complicated algorithm as a fundamental step. This step basically needs to check if a certain tree \(T\) is a minimum spanning tree for a certain graph, which is not something specially hard. The hard part is that needs to have \(O(m + n)\) complexity and that makes the implementation much harder.

It was actually so complicated that it inspired funny paper names:

1. Linear Verification For Spanning Trees, 1984 Komlós
2. A Simpler Minimum Spanning Tree Verification Algorithm, 1997 King
3. An Even Simpler Linear-Time Algorithm for Verifying Minimum Spanning Trees, 2009 Hagerup

I am forever grateful to Hagerup, which is the only author that included his implementation as part of the paper. After a lot of time banging my head against the wall, I was able to find a really subtle typo in the code he provided. A beautiful case of finding the needle in the haystack.

Wrong version from paper:
S = down(D[v], S & (1 << (k + 1) - 1) | (1 << depth[v]));
Corrected version :
S = down(D[v], S & ((1 << (k + 1)) - 1) | (1 << depth[v]));

Fixing this line made my implementation work (at least with my tests).

Ok, but how fast is \(KKT\) anyway?

As I mentioned earlier, I used the google-benchmark code to estimate the runtime complexity of my implementation. Another cool fact is that is also estimates the constants in your implementation.

In Big-\(O\) analysis we ignore constants, but they can make a huge difference in the runtime of your algorithm and how large the instances have to be to make one algorithm “better” than other. You can see my benchmark results here.

Estimated runtime of Borůvka was \(4.67 * N * \log_{2}{N}\) and for \(KKT\) the estimated complexity was \(2357 * N\), where \(N\) here is total edges + nodes in the graph.

So, for sufficiently large \(N\) we expect that \(KKT\) will beat Borůvka. But how large does \(N\) have to be?

So assuming this equation returned by the benchmark library holds for larger graphs, we would need a graph with \(|Nodes| + |Edges| > 9 * 10^{151}\).

A quick research tells us that:

• Total amount of information accumulated by humanity to date is estimated to be around \(2.95 * 10^{20}\) bytes.
• The number of atoms in the observable universe is estimated to be in the order of \(10 * 10^{82}\).

So not only humanity today is not able to store a graph large enough for my \(KKT\) implementation to beat my Borůvka implementation, but even if the graph had the size equal to the amount of atoms in the observable universe that would not be large enough. There is a name for algorithms like that, they are called Galactic Algorithms (:

Final remarks

• Even though Big-\(O\) analysis ignores constants, they can make a certain algorithm impractical for real world instances.
• It is obviously possible to try to reduce the constant of my \(KKT\) implementation, but I don’t believe it will make the algorithm better than the classical alternatives for real world examples.
• The analysis used estimates of the implementation runtime complexity, this will change if a different set of tests are used for benchmarking.
• At least we now have a publicly available implementation of expected linear time algorithm to finding minimum spanning trees.
• Be aware that when you propose a complicated algorithm, you might cause a student to try to implement it 10/20 years later (:

Credits

I want to thank all the amazing algorithms professors that I had in life, who taught me with great enthusiasm and also offered several suggestions on how to improve my thesis/this blog post.

• Marcus Poggi
• Eduardo Laber
• Marco Molinaro
• Daniel Fleischman

Unanswered questions / additional thoughts

• Is it worth the time trying to reduce the constant of my \(KKT\) implementation? A significant speed-up could make this somewhat useful for really large (but real-world) instances.
• A breakdown of the time spent in each function of \(KKT\) implementation would be interesting to see.
• Is there a class of graphs in which \(KKT\) is more “competitive”?

Relevant links

• My final thesis report (portuguese)

Suggestions

I am always open to suggestions and/or feedback, if you have something to say please send me an e-mail