Volkan/source/HotReload/README.md

Hot Reload

Patches a running process's own code in place so that a new build of a function takes effect immediately -- no restart, and every existing caller (including a raw C function pointer someone cached ten minutes ago) picks up the change automatically. This is the full technical reference; see this project's top-level README.md for a quicker overview, feature summary, and build/run instructions if you haven't already.

hot_reload::Context (include/hot_reload/Context.hpp) is the primary, modern C++ API; hot_reload.h is a separate, independently stable plain C API built on top of it, for anything that specifically needs C linkage. Both are fully Doxygen-documented -- see the top-level README's "Documentation" section for how to build that locally, and its "Pick an API" section for which of the two fits what you're writing. source/examples/HotReloadDemo is a full worked example (through the C API; source/tests/ContextTests/Main.cpp is the equivalent through Context directly, concurrency stress test included); this file is the overview neither API's own doc comments have room for, especially the parts you should know are not guaranteed.

To see it run:

cmake -S . -B out -DBUILD_EXAMPLES=ON
cmake --build out
./out/bin/examples/hotreload_demo_host

Then open source/examples/HotReloadDemo/PluginV1/src/Plugin.cpp and PluginV2/src/Plugin.cpp side by side against the output -- they're written to stand in for "the file before your edit" and "after". The same two directories' CppWidget.cpp do the same for a real C++ class with no extern "C" anywhere -- see "Hot reloading C++ symbols" below.

Both of those exist to prove things deterministically, though -- for actually playing with this yourself, see source/examples/HotReloadLiveDemo/README.md instead: a host that stays running, and one plugin file you edit and rebuild as many times as you want while it's live.

How it works, in one paragraph

load() loads a shared library and reads its exported symbol table. reload() loads a new build of that same library, reads its symbol table too, and for every name both builds export as a function, overwrites the first few bytes of the old function with an unconditional jump to the new one's address. Every existing call site -- direct calls, calls through the PLT/GOT, raw function pointers already sitting in some struct -- reaches the old address and immediately redirects, because that's now all that's there. Full byte-level detail, verified against a real assembler rather than transcribed from memory, is in src/Architecture.cpp's file comment. (Written here as plain load()/reload() because the mechanism is the same regardless of which API calls it -- hot_reload::Context::load() directly, or hot_reload_load() through the C API, which calls that same method.)

The two guarantees this library asked to make

"Only executable code changes, never data." This isn't a naming convention you have to follow -- it's mechanical. src/SymbolTable.cpp classifies every exported symbol using the loader's own metadata (an ELF symbol's type + its section's executable flag; a PE export's containing section's characteristics), and Context refuses to patch anything not classified as a function, on either side of a reload. source/examples/HotReloadDemo proves this concretely: plugin_build_marker is an exported int sitting right next to real functions, changes value between V1 and V2 exactly like a function's behavior would, and the demo reads its original address again after reloading to show it's untouched.

"Handle deletion gracefully." A function missing from the new build is reported through HotReloadOptions::on_symbol_event (HOT_RELOAD_SYMBOL_REMOVED) and, by default, its old implementation is simply left running -- nothing is ever patched to a null or garbage address. If you want stale calls to be loud instead, on_deleted_symbol lets you redirect it to a stub of your own. Both policies are exercised in this repo: source/examples/HotReloadDemo/Host supplies a stub; source/tests/HotReloadTests covers the default.

Neither guarantee depends on anything the hot-reloadable module's author has to remember to do correctly -- see "What this cannot detect" below for the one important thing that's true in reverse.

The C++ API: design and thread safety

hot_reload::Context (include/hot_reload/Context.hpp) is a thin public shell: one std::unique_ptr<Impl> member, with Impl defined entirely inside Context.cpp and never named in any header. Every other detail:: header this library has -- ModuleHandle.hpp, SymbolTable.hpp, the rest -- is included by Context.cpp alone, which is what lets Context.hpp stay free of all of them: a caller who only #includes that one header never sees any of this library's own internals, and a change to one of those internals never forces that caller to recompile. It also buys something PIMPL is well known for but worth saying plainly here: Impl holds a std::shared_mutex, which is neither copyable nor movable, yet Context itself is freely movable -- moving one just moves the pointer -- confirmed directly in source/tests/ContextTests/Main.cpp's own runMoveSemantics(). A moved-from Context is left in the same state a moved-from std::unique_ptr is: valid to destroy or move-assign to, nothing else.

Thread safety is a property of Impl's std::shared_mutex, nothing more exotic. load() and reload() take it exclusively (std::unique_lock); findSymbol() takes it shared (std::shared_lock), so concurrent lookups run in parallel with each other and only block when a load()/reload() is actually in progress. This is a claim about this object's own bookkeeping -- the std::unordered_map of loaded modules, specifically -- not about the bytes a reload patches: nothing can make it safe to rewrite a function's machine code while some other thread is, at that exact moment, executing inside it, on any architecture, by any tool. Reload from a quiescent point for the module involved, the same as a single-threaded caller would; see "What this cannot detect" below for the full reasoning. Verified, not just designed this way and assumed correct: source/tests/ContextTests/Main.cpp's own runConcurrencyStress() runs several threads calling findSymbol() against others calling reload() -- some on the very same module name as each other, a genuine race for which build ends up active that the test makes no assertion about, only that nothing crashes or corrupts -- plus several more threads each load()-ing their own distinct module name into the same shared Context, all run under ThreadSanitizer across five separate executions specifically to cover more than one possible thread interleaving. Zero races reported, every time; see the top-level README's "What's actually been tested" table.

Result replaces the C API's split between a returned status and a separate, stateful hot_reload_last_error() call. That split is awkward even single-threaded (an error you have to remember to go ask for, from a call that already finished) and genuinely ambiguous once more than one thread can be calling into the same context: whose "last" error is it? Result::status() and Result::message() are both bundled into the value load()/reload() themselves return, so there is no shared, stateful side-channel for two threads' calls to collide on in the first place -- not a mutex added around the old design, a different design that does not need one for this specific problem. The C API still offers hot_reload_last_error(), because that is part of its own, separately stable contract, and implements it correctly (each calling thread sees its own most recent error on a given context, never another thread's) with a thread_local std::unordered_map in c-api/HotReloadApi.cpp, keyed by a never-reused per-context ID rather than the context's own address -- otherwise a destroyed context's memory being reused by an unrelated later one could, in a narrow window, read back a stale message that was never actually about it.

The patch-writing mechanism in Architecture.cpp itself is unchanged. Each backend's writeJumpAt() still uses a plain memcpy() plus std::atomic_thread_fence() for its write-ordering protocol (payload first, the instruction that actually arms the jump last), not std::atomic_ref. This was a deliberate choice, not an oversight: std::atomic_ref requires the referenced object to be suitably aligned for its type, which this code cannot promise in general -- an x86/x86-64 function's entry point, and the literal address embedded a few bytes into it, can legally sit at any byte offset at all, with no alignment guarantee whatsoever. Applying atomic_ref somewhere that precondition does not provably hold would be undefined behavior, which is strictly worse than the fence-based approach already here -- so rather than apply it selectively (correct on, say, ARM64's and ARM32's naturally-4-byte-aligned literals, wrong everywhere else) for an inconsistent, easy-to-misapply-later gain, every backend keeps the one mechanism that is actually guaranteed correct on all four.

hot_reload::demangle()'s MSVC path gained a mutex. UnDecorateSymbolName, and DbgHelp as a whole, is documented by Microsoft as unsafe to call from more than one thread at once -- already true before this library had any concurrency story of its own, simply never written down. Demangle.cpp now serializes every MSVC-path call through one std::mutex; the GCC/Clang path (abi::__cxa_demangle) needs nothing equivalent, since it keeps no comparable shared state.

Hot reloading C++ symbols (classes, virtual methods, operators)

Everything above works for a real, unmodified C++ mangled name with no changes to this library at all -- classification only ever looks at a symbol's type and section (see src/SymbolTable.cpp), never at what its name looks like, so a class's ordinary method, a virtual method, and an overloaded operator are, mechanically, no different from an extern "C" function. This isn't a theoretical claim: source/examples/HotReloadDemo/Shared/CppWidgetApi.h declares a class with all three, exported with no extern "C" anywhere, living in the same plugin build as the plain-C demo, and source/examples/HotReloadDemo/Host/Main.cpp hot-reloads it -- run the demo (see the top of this file) and watch the CppWidget:: lines in the output.

Virtual methods work automatically, including through a real vtable. A virtual call is dispatched by loading a function pointer out of the object's vtable and calling through it -- and that pointer holds exactly the same address a direct call would, since the plugin's own code populated the vtable with it. Patch that address, and every path that reaches it redirects: a raw function pointer, a direct call, and a vtable slot are all just different ways of holding the same address. The demo proves this directly: it calls widget->virtualTick(x) through ordinary polymorphic dispatch, once before hot_reload_reload() and once after, on the same pre-existing object, and the second call runs the new build's code.

That said, a vtable is data, and changing its layout -- adding, removing, or reordering virtual functions, or changing base classes -- is exactly the data-layout hazard "What this cannot detect" describes below, just in a C++-specific shape: a pre-existing object's vptr still points at the old build's vtable, with the old slot count and order, so new code that assumes the new layout while running against an old object's vtable will read the wrong slot. A newly-constructed object (created after the reload) gets the new vtable and is fine. This library does not check for this -- it isn't something a symbol table carries any information about -- so keep a hot-reloadable class's virtual function set unchanged across a reload, the same discipline as keeping a free function's signature unchanged.

Operators are just functions with unusual mangled names and need nothing special either -- CppWidgetApi.h's operator+ patches exactly like tick() below.

The one real requirement, restated for C++: a function only exists to be patched at all if the compiler emitted an actual out-of-line body for it somewhere addressable. This was already true for extern "C" functions (see "Using it in your own module" below), but C++ makes it much easier to violate by accident:

• A method defined inside a class body (struct S { int f() { ... } };) is implicitly inline, and a caller that includes the header will very often get the body inlined directly into its own compiled code, with no separate symbol left anywhere to patch. This is not hypothetical -- built and inspected while writing this feature:

  struct InlineWidget { int tick(int x) { return x * 2; } };
  int caller(int x) { InlineWidget w; return w.tick(x); }
  

  compiled with optimization on, nm -D on the resulting library shows no InlineWidget::tick symbol at all -- the compiler deleted the separate function entirely, so there is nothing any binary-patching tool, this one included, could ever redirect. caller's own compiled code has to be replaced by reloading caller itself.
• Templates are instantiated per translation unit and, unless explicitly instantiated once elsewhere, typically get inlined at each call site for the same reason.
• The fix, where it applies, is the same one C already needed: declare in a header, define exactly once out-of-line in a .cpp compiled into the reloadable module, and don't let a caller outside that module see the definition (so the compiler never has the option to inline it away). CppWidgetApi.h's methods are declared in the header and defined in PluginV1/src/CppWidget.cpp / PluginV2/src/CppWidget.cpp for exactly this reason.

Mangled names are only stable within one ABI family. GCC and Clang implement the same (Itanium) C++ ABI and mangle the demo's CppWidget identically -- confirmed directly: the demo was built and run with both compilers, and separately cross-compiled with MinGW and run under Wine, all using the exact same hardcoded mangled-name string in Host/Main.cpp. MSVC uses its own, unrelated scheme. This isn't a new limitation this library introduces -- you were always going to reload with the same toolchain you started a session with -- but it's worth stating plainly for mangled names specifically, since unlike an extern "C" name, a mangled one simply won't match at all across the two families.

Looking up a mangled name is genuinely more annoying than an extern "C" one, which is the practical reason to prefer the latter for anything the host needs to call by a human-typed string. There's no portable way to ask the compiler for another declaration's mangled name at compile time; the demo gets it the same way you would in practice, with nm -D --defined-only <library> | c++filt. Two ways around this, both shown in the demo:

1. Keep one extern "C" factory/entry function (make_cpp_widget() in the demo) and reach everything else through it -- a returned object's virtual methods then need no lookup at all (see above).
2. For a method that isn't virtual, call hot_reload_demangle() on whatever name you do have (e.g. for logging -- see HotReloadOptions::on_symbol_event's output in the demo, where _ZN9CppWidget4tickEi prints as CppWidget::tick(int)), or accept the manual nm | c++filt lookup as a one-time cost, same as the demo does for CppWidget::tick.

hot_reload_demangle() renders a real mangled name for display (via __cxa_demangle on GCC/Clang/MinGW, UnDecorateSymbolName on MSVC) and returns anything else -- including a plain extern "C" name -- completely unchanged, so it's safe to call on every HotReloadSymbolEventInfo::name unconditionally, as the demo does. It never changes what a name means for lookup purposes; it exists purely so a log is readable.

One general C++-plugin caveat, not specific to hot-reloading: exceptions and RTTI (dynamic_cast, typeid) generally should not cross the boundary into or out of a dynamically-loaded module at all -- this is already true of any dlopen()/LoadLibrary()-based plugin architecture, for the same reasons cpp-style-guide.md section 11 gives for the plain C boundary, and hot-reloading a module doesn't change it either way. The demo's delete widget relies on new and delete resolving to the same allocator across the boundary, which holds on Linux/macOS as tested here; it's worth double-checking on Windows if you link the CRT in an unusual way (e.g. mismatched static/dynamic CRT between the host and a plugin).

Why do std::string/std::vector symbols show up as PATCHED?

Because they're real, addressable functions too, and classification doesn't -- can't -- know that a symbol "belongs to the standard library" as opposed to your own code. Confirmed directly: any plugin that uses std::string/std::vector<T> internally will show template instantiations like std::vector<int>::_M_realloc_insert<...> getting HOT_RELOAD_SYMBOL_PATCHED on every single reload, even one that changed nothing about how you use them -- because these are genuinely present, genuinely exported (with default visibility, by default, on every build tested here), and genuinely at a new address every time, since that's just true of everything in a freshly-loaded .so/.dll.

This is safe. It's the exact same template instantiation in both builds -- same mangled name, same object layout, same ABI, and (using the same compiler and standard library on both sides, which you already need for mangled names to match at all -- see above) functionally equivalent code. Redirecting old calls to the new copy changes where the logic runs, never what it does.

It is not fixable by hiding symbols, and that's not just an unimplemented feature. The obvious fix -- compile with -fvisibility=hidden -fvisibility-inlines-hidden -- does not work here, confirmed directly: libstdc++'s headers mark these template instantiations default visibility explicitly, in the header itself, specifically so multiple .sos can share type identity for RTTI and exception handling across shared-library boundaries. That annotation wins over your translation unit's own -fvisibility=hidden default, on purpose, and this library has no way to override it that wouldn't also risk breaking that cross-DSO guarantee for anyone who needs it.

A blanket "don't patch weak-linkage symbols" rule would be the wrong fix even if it worked, which is why this library doesn't do that either: weak/COMDAT linkage is also exactly how a hot-reloadable template of your own would be classified. A rule that reliably filters out the standard library's internals would just as reliably filter out your own reloadable generic code.

What actually helps, if the log's noise level bothers you, is narrowing your plugin's export surface with hot_reload_restrict_exports() (cmake/HotReload.cmake) and HOT_RELOAD_EXPORT (hot_reload.h) -- see "Using it in your own module" below. This doesn't remove the standard-library instantiations specifically (see above), but it does stop your own internal helpers, and (on GCC/Clang, if a target statically links its C++ runtime) incidental runtime-library internals, from becoming part of the diff at all -- both real cases observed while building this library's own examples. Beyond that, filtering the event log for display is a one-line addition in your own on_symbol_event callback -- e.g. skip anything whose hot_reload_demangle()'d name starts with "std::".

Scope: what's actually implemented and checked

	x86	x86-64	ARM64	ARM32
Jump-patch backend	yes	yes	yes	yes
Landing pad handled	ENDBR32	ENDBR64	BTI	--

ARM32's own row needs a caveat the table can't carry: "yes" means a function's address decides ARM vs. Thumb state, not a build-wide setting, and both are handled -- see the "What was actually run" bullet below for exactly how that was confirmed, not just reasoned through.

Compilers. GCC and Clang share one backend (including MinGW, which is one or the other targeting Windows); MSVC has its own /hotpatch-based path in cmake/HotReload.cmake and its own PE export-table reader in SymbolTable.cpp.

What was actually run, not just compiled, while building this:

• Native GCC and Clang on Linux/x86-64: the full demo, both compilers, including a real ENDBR64 landing pad this toolchain turned out to emit by default -- see src/Architecture.cpp's file comment.
• Cross-compiled to ARM64 and run under qemu-aarch64: the full demo, twice -- once plain, once with -mbranch-protection=bti -- to exercise the BTI-landing-pad path on real (emulated) ARM64 semantics, not just have it compile.
• Cross-compiled to ARM32 and run under qemu-arm: the full demo and test suite, across both of this architecture's incompatible instruction-decoding states (the default Thumb-2, and ARM state forced with -marm) and across -O0 through -O3. This is the one architecture here whose jump-patch backend cannot pick a single instruction encoding at compile time the way the other three do -- which of the two states a given function is in is a property of that function alone, read from the same bit the ARM EABI already marks every function symbol with (set for Thumb, clear for ARM; a loadedBase + st_value sum this library already computed the same generic way for every architecture, so nothing in SymbolTable.cpp needed to change for this). Thumb state carries a second wrinkle on top: its own literal-load jump instruction needs to sit on a 4-byte boundary, which nothing guarantees for a Thumb function in general (only 2-byte alignment is). Rather than trust that reasoning alone, a plugin was built with a function whose compiled address was confirmed, via its own symbol table entry, to land 2 bytes off that boundary, then loaded, reloaded, and called through across the reload under qemu-arm -- proving the one realigning NOP this backend adds for exactly that case actually works, not just that it assembles. Building the test suite here also surfaced a real, architecture-specific gap in the suite itself: its "too small to patch" function, reliably minimal on every other architecture as a plain empty C++ body, picks up a big enough unoptimized frame-pointer prologue on this one at -O0 to tie this backend's own jump size exactly -- closed with a third implementation of that one function, hand-written at file scope instead of compiler- generated, for this architecture specifically (see source/examples/HotReloadDemo/Shared/PluginApi.h's doc comment on plugin_tiny_function). 32-bit ARM running under MSVC was not attempted -- no Windows-on-ARM32 environment was available to build or verify against, and it is a rare enough target in practice that, unlike x86/x86-64/ARM64, this library makes no claim about it either way.
• Cross-compiled with MinGW and run under Wine: the full demo, exercising the real Win32 LoadLibrary/VirtualProtect/ FlushInstructionCache calls and the PE export-table parser. This run is also why the demo plugins now set WINDOWS_EXPORT_ALL_SYMBOLS ON -- the first attempt silently exported nothing under an MSVC-style build until that was added. Re-run after adding CppWidgetApi.h's C++ class: confirmed the PE reader also correctly classifies a vtable and typeinfo as data (not code) on Windows, not just on ELF, and that GCC and Clang produce identical mangled names for the same class (the demo's hardcoded _ZN9CppWidget4tickEi lookup string was derived from a native GCC build but also worked unmodified against this MinGW/Wine build and the separate native Clang build).
• MSVC was never run directly in the environment that built this library -- there is no Windows machine or MSVC install available there. It has, since, been built and live-tested on real MSVC by someone using this library, surfacing four real fixes now folded in: windows.h must be included before dbghelp.h (the reverse order fails to compile -- dbghelp.h assumes types like HANDLE are already defined rather than including their own headers), NOMINMAX needs defining before windows.h in every file that includes it (SymbolTable.cpp concretely needs this -- without it, windows.h's own min/max macros substitute into that file's std::max/std::min calls and it fails to compile), MSVC needs dbghelp.lib linked explicitly for UnDecorateSymbolName (source/HotReload/CMakeLists.txt now does this whenever MSVC is true, which also covers clang-cl), and source/examples/HotReloadLiveDemo's reload-retry logic needed widening (see that example's own file for why). The MSVC-specific code (/hotpatch, IMAGE_EXPORT_DIRECTORY parsing, VirtualProtect, FlushInstructionCache) was written directly against Microsoft's documented structures and behavior before any of that feedback existed, and the equivalent PE-reading code was separately compiled clean against real <windows.h> headers via MinGW -- between the two, treat it as real-world-checked now, not merely reasoned through, though obviously with less first-hand confidence than everything that was directly, repeatedly run in this project's own development loop (native GCC/Clang, ARM64 and ARM32 under QEMU, MinGW under Wine).
• macOS (Mach-O) was not implemented. Nothing in the request named it, and it would need a third format reader alongside SymbolTable.cpp's ELF and PE branches. readExportedSymbols() is the one function that would need it.

What this cannot detect

A changed function signature. Patching redirects control flow at a fixed address; it has no way to know from a symbol table alone that void tick(int) became void tick(int, int). If a function's signature changes, give it a new exported name instead of reusing the old one -- the old name is then correctly reported as HOT_RELOAD_SYMBOL_REMOVED and the new one as HOT_RELOAD_SYMBOL_ADDED, rather than being patched into a mismatched calling convention.

A data layout change reached only through code that still gets patched. The library guarantees it never touches a data symbol directly. It cannot guarantee that a patched function is safe to run against a struct/class instance that already exists in memory with the old layout -- e.g. a game object allocated before the reload, if the new code adds a field to its type. This is a correctness property of your own code across the reload boundary, not something a symbol table (which carries no field-offset information) can check. If you need this checked, the extension point is the same place: Context::reload() -- diffing the two builds' debug info (DWARF or PDB) for layout changes in types touched by patched functions is real work, genuinely useful, and out of scope for what's here now.

Being called concurrently with the code it's patching. The intended use is the same as every other tool in this space (Unreal's Live Coding, Handmade Hero's hot reload, etc.): call hot_reload_reload() from a quiescent point -- your main thread between frames or ticks -- where nothing else is actively calling into the module you're reloading. The write order in src/Architecture.cpp (payload bytes before the opcode that arms them, with a release fence between) protects the realistic case where a call arrives right at that boundary. It does not protect a thread that is genuinely, actively executing through the exact bytes being patched at that moment -- doing that in general on a variable-length ISA needs a signal-handler-based retry protocol, a substantially bigger mechanism than a dev-loop tool like this one calls for. See that file's comment for the full reasoning.

Known, accepted gaps

• A .so with its section header table deliberately stripped, truncated, or otherwise corrupted reads back as exporting no functions at all (empty, not a crash) -- SymbolTable.cpp's ELF reader uses section headers to find .dynsym/.dynstr, which is simpler and easier to get right than walking .dynamic's DT_* tags the way the dynamic linker itself does, at the cost of this one edge case for a deliberately-stripped file. Every offset, size, and index this reader trusts is bounds-checked against the file's actual size before use -- confirmed directly by fuzzing the section header table of a real plugin build: 1500 randomly corrupted variants (each still a file the OS loader itself accepts via dlopen()), zero crashes. An earlier version of this same reader, without those checks, crashed on 69 of an initial 300. Stripping section headers from a .so you are actively hot-reloading is, separately, an unusual step essentially never taken by accident.
• PE exports have no per-symbol size. Unlike ELF's st_size, which backs a real safety check, the Windows path estimates size from the gap to the next exported function and can only ever prove "not enough room," never prove "enough" -- see SymbolTable.cpp's file comment. /hotpatch (applied automatically by hot_reload_enable_patchable_functions()) is the real safety mechanism on Windows; treat the size estimate as a bonus, not a guarantee.
• A forwarder PE export (one that re-exports another DLL's function) is classified as non-function and left alone, not followed.

Diagnosing a failed load

Status::LoadFailed (HOT_RELOAD_ERROR_LOAD_FAILED through the C API) alone doesn't say why -- a missing file, a permissions problem, a corrupt or wrong-architecture image, and a genuinely undefined symbol all look the same from the status code alone. Result::message() carries the platform's own description (dlerror() on POSIX, a formatted GetLastError() on Windows) directly -- or, through the C API, call hot_reload_last_error(ctx) right after the failing hot_reload_load()/hot_reload_reload() for the same thing (see "The C++ API: design and thread safety" above for exactly how that call stays correct even with more than one thread sharing a context).

The specific case that motivated adding this, reproduced directly while writing it: a non-inline static class member that is declared but never given an out-of-class definition.

class Randomizer
{
	static std::mt19937& gen() { return m_gen; } // ODR-uses m_gen
	static std::mt19937 m_gen; // declared here -- never defined anywhere
};

This compiles cleanly and links cleanly into a shared library -- unlike an executable, a shared library is allowed to keep undefined symbols by default, on the assumption that whatever eventually loads it will supply them. It only fails once dlopen(..., RTLD_NOW) (this library always uses RTLD_NOW, deliberately -- see the comment in ModuleHandle.cpp on why a clean, catchable failure right here beats a deferred, uncatchable one under RTLD_LAZY) tries to eagerly resolve every symbol and can't find this one anywhere in the process. Confirmed directly: building the same class with the code path that uses it left uncalled produces a .so with no trace of the missing symbol at all (the compiler drops the unused, never-instantiated inline method entirely); the moment something calls it, hot_reload_last_error() reports exactly undefined symbol: _ZN10Randomizer4m_genE. The fix is the one C++17 already offers: mark it inline static (with its initializer, if it has one) instead of a bare static declaration, the same way you'd fix this in any shared library, hot-reloaded or not.

Using it in your own module

1. extern "C" isn't required -- a real C++ mangled name works too (see "Hot reloading C++ symbols" above) -- but it's still the simplest choice for anything you want to look up by a plain, human-typed name, and the only way to get a name stable across compilers.
2. Build it as its own SHARED library target and call hot_reload_enable_patchable_functions(<target>) (cmake/HotReload.cmake) on it, so every exported function has guaranteed room for a jump. Without this, reload still works for any function whose compiled body happens to be large enough on its own -- functions that aren't get skipped (HOT_RELOAD_SYMBOL_SKIPPED_TOO_SMALL), not corrupted.
3. Decide how much of the target's export surface you want to be deliberate about:
   • Simplest: do nothing else. On GCC/Clang/MinGW this exports every symbol with external linkage by default; on MSVC, also set WINDOWS_EXPORT_ALL_SYMBOLS ON to match (MSVC exports nothing by default otherwise). source/examples/HotReloadDemo's plugins use this style.
   • Recommended for a real project: call hot_reload_restrict_exports(<target>) (cmake/HotReload.cmake) instead, and mark each intended entry point with HOT_RELOAD_EXPORT (hot_reload.h) -- extern "C" HOT_RELOAD_EXPORT int my_function(...) for a plain-name free function (that exact order -- GCC/Clang want the attribute after extern "C"), or just HOT_RELOAD_EXPORT alone on a C++ class/method you want exported with its real mangled name intact. This keeps anything you didn't explicitly mark -- your own internal helpers, or (on GCC/Clang, if the target statically links its C++ runtime) incidental runtime-library internals -- out of the diff entirely. It does not narrow out std::string/std::vector template instantiations specifically; see "Why do std::string/ std::vector symbols show up as PATCHED?" above for why not, and why that's fine either way. source/examples/HotReloadLiveDemo's plugin uses this style -- compare the two examples' exported symbol lists (nm -D --defined-only <path> | c++filt) to see the difference directly.
4. Have your host load() it once at startup (hot_reload::Context, or hot_reload_load() through the C API) and reload() it after every rebuild, from a point where nothing else is calling into it (see "What this cannot detect" above).
5. Rebuilding to the same output path every time is fine -- Context stages every load through a fresh, uniquely-named copy internally specifically so your build system's exact write pattern can't cause a stale reload (a known gotcha for this style of tool; see Context.cpp's stagePathForLoad()). On Windows, each staged copy backing a still-loaded module can't be deleted for as long as that module stays mapped -- the rest of the process's lifetime, by design -- so a long-running session accumulates one such file per reload; hot_reload_load() sweeps up whatever a previous run left behind, so this doesn't grow without bound across sessions, only (unavoidably) within one very long one. See source/examples/HotReloadLiveDemo/README.md's own section on this for the full story, including why "Rebuild Solution" (or any other full clean) separately fails outright while a host built from this library is running, for an unrelated reason -- it also tries to delete the host's own executable, which Windows refuses while it's running, and which has no staging workaround at all.