The Bridge Header

Why C, not C++

C++ has classes, namespaces, templates, name mangling, exceptions, and ABIs that change between compiler versions. Swift, C#, Python, Rust, and JavaScript don't speak any of those things. They speak C — flat function calls, primitive types, opaque pointers, no exceptions, predictable layouts. C is the lingua franca of operating systems, and the language every other language has bindings for.

So we don't try to expose ChessEngine::best_move(Board&, int) directly. We expose chess_best_move(void* engine, int depth, char* out_move). The C++ implementation lives behind it, but the surface is pure C.

The bridge header

// chess_bridge.h — pure C, included from C++, Swift (via modulemap),
// and C# (via [DllImport]).
#ifndef CHESS_BRIDGE_H
#define CHESS_BRIDGE_H

#ifdef __cplusplus
extern "C" {
#endif

typedef struct ChessEngine ChessEngine;     // opaque

ChessEngine* chess_create(void);
void         chess_destroy(ChessEngine*);

// FEN string in / out — the standard chess position notation.
void         chess_set_position_fen(ChessEngine*, const char* fen);
void         chess_get_position_fen(ChessEngine*, char* out_buf, int buf_len);

// "e2e4" / "e7e8q" style moves.
int          chess_apply_move(ChessEngine*, const char* move);     // 0=ok, 1=illegal
void         chess_best_move(ChessEngine*, int time_ms,
                              char* out_buf, int buf_len);

#ifdef __cplusplus
}     // extern "C"
#endif

#endif

Six functions. Pure C types: pointers, const char*, ints, output buffers. The opaque typedef struct ChessEngine ChessEngine means callers can hold an engine handle without knowing what's inside. The extern "C" wrapper, on the C++ side, tells the compiler to drop name mangling so the symbols look like plain C functions in the linker output.

The C++ implementation behind the bridge

// chess_bridge.cpp — implemented in C++, compiled into the same binary.
#include "chess_bridge.h"
#include "engine.hpp"     // real C++ engine

struct ChessEngine {
    engine::Engine impl;
};

extern "C" ChessEngine* chess_create(void) {
    return new ChessEngine{};
}

extern "C" void chess_destroy(ChessEngine* e) {
    delete e;
}

extern "C" int chess_apply_move(ChessEngine* e, const char* m) {
    try {
        return e->impl.apply(m) ? 0 : 1;
    } catch (...) {
        return 2;
    }
}

// …and similar wrappers around best_move, get_position_fen, etc.

Note the try/catch(...). C exception unwinding across language boundaries is undefined behaviour — Swift and C# can't reliably catch a C++ exception. So the bridge swallows them and converts to a status code. That's the contract: this is a C function and never throws.

One more rule: every pointer that crosses the boundary has clear ownership. chess_create returns a pointer the caller must release with chess_destroy. Output buffers are allocated by the caller and filled by the function. The C side never frees memory the C++ side allocated, and vice versa. Cross-allocator memory transfer is the most common source of crashes in language bridges.

How Swift sees it

// In Swift — given a modulemap that imports chess_bridge.h
import ChessBridge

final class Chess {
    private let handle: OpaquePointer

    init() {
        guard let h = chess_create() else { fatalError() }
        self.handle = h
    }
    deinit { chess_destroy(handle) }

    func apply(_ move: String) -> Bool {
        return chess_apply_move(handle, move) == 0
    }
}

Swift wraps the opaque pointer in a class. init creates the engine, deinit destroys it — Swift's automatic reference counting takes care of the lifetime. The C function is directly callable: no glue code, no marshalling layer. That's the magic of the bridge.

How C# sees it

using System;
using System.Runtime.InteropServices;

internal static class ChessNative {
    [DllImport("chess.dll")]
    public static extern IntPtr chess_create();

    [DllImport("chess.dll")]
    public static extern void chess_destroy(IntPtr e);

    [DllImport("chess.dll", CharSet = CharSet.Ansi)]
    public static extern int  chess_apply_move(IntPtr e, string move);
}

C# calls native code through P/Invoke (DllImport). The strings get marshalled automatically. The IntPtr is C#'s name for an opaque pointer. Same shape as the Swift side, different syntax. The exact same chess_bridge.h, the exact same C++ engine, two host languages, two native apps.

What flows across the boundary

The principle: keep traffic over the bridge infrequent and data-only. A few rules of thumb:

• Pass primitives or strings, not C++ objects. std::string doesn't survive the trip; convert to const char*.
• Don't pass callbacks if you can avoid them. A C function pointer works in both directions, but Swift closures and C# delegates need extra care to keep alive across the call.
• Batch where you can. Crossing the boundary 100,000 times in a loop is a real cost; one call returning a buffer of 100,000 results is not.
• Strings are the trickiest. UTF-8 is the only encoding both sides agree on. Specify it explicitly in the C# attribute and the Swift binding, and your text won't show as ?????.

Why this is the architecture

You write the engine once, in C++, and ship it to every platform. Apple? Compile for arm64+x86_64, link from a Swift app. Windows? Compile to a DLL, P/Invoke from C#. iOS? Same engine. Linux? Same engine. Android via NDK? Same engine. The logic is platform-independent; only the UI is platform-specific. That's why nearly every cross-platform app you've ever used has a C or C++ core: VS Code (Electron over a web stack, but its native pieces are C++), Photoshop, Spotify (libspotify is C), every video game (the engine is C++; the platform shell isn't). The bridge header is the seam.

Write the hard part in C++. Write the pretty part in whatever the OS prefers. Connect them with a flat C surface.

What's next

The bridge is one half of the puzzle: how does C++ expose itself? Next week is the other half on Apple: how does Swift consume it? We'll write Objective-C++ wrappers (the dialect that's both C++ and Objective-C — yes, really), expose Swift-friendly types, and build a chess UI in SwiftUI that drives the C++ engine.

Week 45 is macOS Native.