carbOnPluginShutdown

Defined in carb/PluginCoreUtils.h

void carbOnPluginShutdown()

An optional function that a plugin author can export from their plugin to shutdown their plugin.

The Framework will call this function when directed to unload a plugin, immediately before calling carbOnPluginPostShutdown and before requesting that the OS release the plugin library. This function will also be called if carb::Framework::unloadAllPlugins is called, but not if carb::quickReleaseFrameworkAndTerminate is called. This serves as a guide for plugin authors.

This function is mutually exclusive with carbOnPluginQuickShutdown; either this function or that one is called depending on the shutdown type.

Providing this function is completely optional.

Generally, this function should be provided if carbOnPluginStartup or carbOnPluginStartupEx is provided in order to clean up the work done in the startup function.

Any interfaces declared as a dependency in CARB_PLUGIN_IMPL_DEPS will still be available to this plugin when this function is called.

During shutdown, if a circular reference exists between interfaces acquired by this plugin and those interfaces (possibly indirectly) acquiring interfaces from this plugin, then it is possible that interfaces acquired by this plugin may already be shut down. Using carb::getCachedInterface or carb::Framework::tryAcquireInterface may result in an error log being issued. In this case, carb::Framework::tryAcquireExistingInterface will only acquire the interface if the plugin providing it is still started.

Once this function returns successfully, the Framework considers your plugin as shut down and will typically proceed to unload the library.

Typical things this function might do:

  • Deallocate memory and data structures for your plugin

  • Report on leaked objects

  • Shut down libraries and subsystems

The type of this function is carb::OnPluginShutdownFn and named kCarbOnPluginShutdownFnName.

Warning

This function should not attempt to acquire any interfaces that the plugin has not previously acquired. In other words, only use interfaces in this function that the plugin has already acquired.

Note

The thread context must be the same when this function returns as when the function is called (i.e. if called within a fiber context, the same thread must return). This function does not allow context switches even when used with carb.tasking.plugin.