Skip to content

libobs, docs: Document intended use of obs_module_unload #13327

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
notr1ch wants to merge 1 commit into
base: master
Choose a base branch
from
Open

libobs, docs: Document intended use of obs_module_unload #13327

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion docs/sphinx/reference-modules.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment on lines +64 to +67
Copy link
Copy Markdown
Member

@PatTheMav PatTheMav Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't we rather ensure that any data that libobs gets from a module is actually refcounted? Because this advice sounds like an anti-pattern to me. If the module is the owner of the data, then libobs can and has to assume that this data can go "poof" at any point.

Either libobs is the owner of the objects (and thus can keep them alive via strong references) and just shares it with modules, then modules simply "release" their strong references. Or the modules are the owners of the objects, then libobs needs to retain a strong reference to ensure the lifetime of the objects.

Copy link
Copy Markdown
Member Author

@notr1ch notr1ch Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is mostly about module internals and the backend of the sources or other functions they provide - e.g. obs-text will call GdiPlusShutdown on unload, which breaks all existing references libobs holds (calling update or destroy accesses freed memory). This is designing around leaked references - usually OBS will have released and destroyed anything provided by the module, but as we all know, 3rd party plugins prevent a fully correct ref counted system from working.


After this function returns, do not make any further libobs API calls
outside of libobs callbacks.

---------------------

Expand Down
16 changes: 15 additions & 1 deletion libobs/obs-module.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 */
Expand Down
Loading