From 6d0083dd61160574c57bfa8047cb7c9a034747b8 Mon Sep 17 00:00:00 2001 From: Richard Stanway Date: Tue, 14 Apr 2026 01:29:39 +0200 Subject: [PATCH] libobs, docs: Document intended use of obs_module_unload obs_module_unload was never properly documented, so some plugins use it to free resources, some use it to save data, etc. While libobs tries to ensure all objects are shut down and destroyed before calling unload, if another plugin is holding a strong reference, or if a reference leak has occurred, libobs may need to call back into a plugin-provided object's destroy function even after obs_module_unload has returned. If the plugin has freed memory or other resources needed for the callback then this likely results in a crash. Going forward, we should document that obs_module_unload is now intended only for saving data and releasing references, and that calling libobs after it returns is not allowed. For cases where resource cleanup is actually needed (for example, an external out of process helper needs to be shut down or a release call to a hardware driver), a new obs_module_destroy callback is intended to be added in a future version. --- docs/sphinx/reference-modules.rst | 14 +++++++++++++- libobs/obs-module.h | 16 +++++++++++++++- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/reference-modules.rst b/docs/sphinx/reference-modules.rst index b799355dc..c93af423b 100644 --- a/docs/sphinx/reference-modules.rst +++ b/docs/sphinx/reference-modules.rst @@ -55,7 +55,19 @@ to communicate with libobs and front-ends. .. function:: void obs_module_unload(void) - Optional: Called when the module is unloaded. + Optional: Called when libobs is shutting down and the module is about + to be unloaded. All libobs objects are still active and valid at this + point. Use this function to save user settings and release any strong + references that the module itself is holding to libobs objects (sources, + canvases, outputs, encoders, and services). + + Do not attempt to release or destroy any still-active objects provided + by the module - ensure that they can continue functioning even after + returning from this function, as libobs may still need to call into the + module's callbacks (e.g., destroy) to clean up any remaining instances. + + After this function returns, do not make any further libobs API calls + outside of libobs callbacks. --------------------- diff --git a/libobs/obs-module.h b/libobs/obs-module.h index c7b9efce1..1c657c357 100644 --- a/libobs/obs-module.h +++ b/libobs/obs-module.h @@ -100,7 +100,21 @@ bool obs_module_load(void) */ MODULE_EXPORT bool obs_module_load(void); -/** Optional: Called when the module is unloaded. */ +/** + * Optional: Called when libobs is shutting down and the module is about + * to be unloaded. All libobs objects are still active and valid at this + * point. Use this function to save user settings and release any strong + * references that the module itself is holding to libobs objects (sources, + * canvases, outputs, encoders, and services). + * + * Do not attempt to release or destroy any still-active objects provided + * by the module - ensure that they can continue functioning even after + * returning from this function, as libobs may still need to call into the + * module's callbacks (e.g., destroy) to clean up any remaining instances. + * + * After this function returns, do not make any further libobs API calls + * outside of libobs callbacks. + */ MODULE_EXPORT void obs_module_unload(void); /** Optional: Called when all modules have finished loading */