libobs, docs: Document intended use of obs_module_unload

[notr1ch]

Description

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.

Motivation and Context

The shutdown process currently causes a lot of crashes due to different plugins making different assumptions. Several 1st-party plugins also violate this and will need fixing.

How Has This Been Tested?

N/A

Types of changes

• Documentation (a change to documentation pages)

Checklist:

• I have read the contributing document.
• My code has been run through clang-format.
• My code follows the project's style guidelines
• My code is not on the master branch.
• My code has been tested.
• All commit messages are properly formatted and commits squashed where appropriate.
• I have included updates to all appropriate documentation.

[PatTheMav]

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.

[notr1ch]

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.