Plugins and hosts#
What a plugin that embeds anira must know about the host it runs in: engine symbols, shared engine libraries, a host’s own tanh-lib, and unloading.
Keeping engine symbols private#
Symptom. A plugin crashes, or fails with “OrtGetApiBase resolved to an ONNX Runtime that does
not support the API version”, inside one host (Ableton Live 12 bundles its own ONNX Runtime) but
works standalone and elsewhere. Cause: engine symbols the plugin exports bind across modules
(ELF interposition, weak-symbol coalescing on macOS such as Ort::Global<void>::api_), so the
plugin’s engine calls reach the host’s runtime.
Use anira’s build. It links one copy of each engine, privately, and exports none of it. Engine linkage follows
BUILD_SHARED_LIBS: a sharedlibaniralinks the shared engines, a static one the static archives, and an engine without that linkage is disabled (LibTorch is shared-only, ExecuTorch static-only).Static archives are linked on demand and hidden (
-load_hiddenon macOS,--exclude-libson ELF), and anira compiles with hidden visibility (tanh_apply_symbol_policy).A static
libanirahas no export decoration (ANIRA_APIis empty underANIRA_STATIC, which the CMake package defines).A shared
libanirapins its export table to theanira_*entries (tanh_set_export_allowlist(anira SYMBOL "anira_*"), checked byanira_symbol_baseline), since visibility alone cannot hide what a header stamps default-visible.The ONNX Runtime adapter refuses a runtime older than the API anira was built against, at the engine’s init (the first prepare that loads one of its models, or a context’s capability probe).
Your own engine code: a translation unit that includes an engine header links that engine’s target,
target_link_libraries(your_plugin PRIVATE anira::anira anira::onnxruntime), and compiles with hidden visibility (CXX_VISIBILITY_PRESET hidden,VISIBILITY_INLINES_HIDDEN ON). Weak symbols an engine header instantiates in your objects are hidden only by your own setting.Export the entry points alone. With anira’s CMake package, two lines do it for a CLAP plugin (
examples/clap-audio-plugin/CMakeLists.txt):tanh_apply_symbol_policy(my_plugin) tanh_set_export_allowlist(my_plugin SYMBOL clap_entry)
By hand:
-Wl,-exported_symbols_liston macOS (_bundleEntry,_bundleExit,_GetPluginFactoryfor a VST3) or a version script on Linux that lists the same names underglobal:andlocal: *;(a CLAP plugin’s one name isclap_entry). This is required on macOS for a static anira with ExecuTorch, whose force-loaded archives ld64 cannot hide. Verify withnm -gU(macOS) ornm -D --defined-only(Linux): no engine symbol may appear.tanh_add_export_check(cmake/tanh/check-exports.cmake) runs the same check in CTest.Strip dead code (optional): anira compiles with one section per function, and a shared
libaniralinks with--gc-sections/-dead_strip//OPT:REF. A static one has no link of its own: pass the flag in your plugin’s link.examples/clap-audio-pluginhas the whole set,-fno-gnu-uniqueunder GCC included.
A host that uses tanh-lib itself#
Nothing to do: the two copies never meet, with a shared or a static anira, on every platform.
anira builds tanh-lib’s core from its own pin (
cmake/tanh-lib-pin.cmake) under its own FetchContent name (anira_tanh_lib), compiles it hidden intolibaniraand installs nothing of it, in the inline namespacethl::anira. Your tanh-lib is in its default namespacethl::v<major>_<minor>or one you chose.Code spells both
thl::…, but no symbol shares a mangled name (_ZN3thl5anira…against_ZN3thl4v0_5…), templates and inline functions included. So your logger, level, callback and threads stay yours, your tanh-lib may come at any version, before or after anira, and the link order does not matter.anira’s concurrentqueue is renamed the same way (
anira_moodycamel).CTest proves both:
anira_abi_namespacesfails on anythlsymbol outsidethl::aniraand anymoodycamelone.consumer_tanh_firstlinks a host’s own shared tanh-lib beforeanira::aniraand checks that the loggers stay apart.
Unloading a plugin#
A host unloads a plugin (dlclose / FreeLibrary) once its last instance is gone, and a
thread still running inside it would then execute unmapped code. anira holds the invariant no
anira thread exists once the last handler and context are destroyed: the last handler’s destructor
stops and joins the inference pool before it returns, and the log drain thread stops with the last
context or handler. The core’s state is never destroyed while the library is loaded, so calling
into anira stays valid even from late static destructors.
Tear down from the instance or the module-exit entry point (CLAP
deinit, VST3ExitDll): every handler, then every context (Teardown and unloading). Never from the plugin’s static destructors orDllMain, which run inside the unload under the loader lock. On Windows callanira_shutdown()there after the handlers and contexts, asexamples/clap-audio-plugindoes: it is idempotent and refuses withANIRA_ERROR_INVALID_STATEwhile a context or handler still exists.The backstop on Linux and macOS: a library-unload hook joins an idle pool. An inference in flight gets up to two seconds. One still running then can never finish during the unload, so the hook writes
anira: the library is being unloaded while an inference is still running ...to stderr and aborts instead of hanging the host.At process exit the core’s exit handler stops the pool earlier and waits up to two seconds, before the engines’ static state is torn down. The hook then joins without a bound, and the process exits normally. Neither waits for the core’s lifecycle lock when the exiting thread holds it, so an engine that ends the process from inside a prepare exits with its own status. On Windows nothing at
DLL_PROCESS_DETACHmay join a thread.Your own inference threads (
context.threads(0)andanira::InferenceThread) are yours to stop before the library can unload.A library that never unloads under GCC/Linux: glibc keeps any object with an
STB_GNU_UNIQUEsymbol. Compile your plugin with-fno-gnu-uniqueand hidden visibility, as anira does.nm -DC your_plugin.so | grep ' u 'must print nothing.macOS never unloads a plugin with thread-local storage, which the static ONNX Runtime, LiteRT and ExecuTorch archives have. That is harmless: it stays mapped until the host quits.
test/contracts/unload covers the unload: it loads and unloads a plugin-shaped module from an
executable that does not link anira, checks that it is really unmapped (skipped where macOS keeps
the image mapped), and death-tests an unload and an exit with an inference in flight.