carbOnPluginStartup

void carbOnPluginStartup()

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

The Framework will call this function after carbOnPluginPreStartup when starting the plugin (the first time an interface is acquired from the plugin). This serves as a guide for plugin authors.

Providing this function is completely optional.

Generally, if this function is provided, a carbOnPluginShutdown should also be provided to cleanup any work done by this function.

This function is superseded by carbOnPluginStartupEx, which allows startup to fail gracefully. If that function does not exist, this function is called if it exists.

Any interfaces declared as a dependency in CARB_PLUGIN_IMPL_DEPS will be available to this plugin by the time this function is called.

This function is allowed to acquire interfaces and interact with the Framework normally (e.g. add hooks, etc.). However, keep in mind that this function is called by the Framework when the Application or another plugin is trying to acquire an interface from this plugin; actions that result in recursively starting the plugin will result in failure to acquire the interface. However, your plugin is allowed to acquire other interfaces from itself in this function.

Once this function returns, the Framework considers your plugin as initialized.

Typical things this function might do:

Allocate memory and data structures for your plugin
Load settings from carb::settings::ISettings (if available)
Start up libraries and subsystems

The type of this function is carb::OnPluginStartupFn and named kCarbOnPluginStartupFnName.

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). However, if carb.tasking.plugin is used, this need not be the case as Carbonite can handle that case properly.

Warning

It is very important that no Carbonite functionality (logging, Framework, profiling, etc.) is used prior to when the Framework calls the carbOnPluginStartup function at plugin initialization time! This includes but is not limited to static initializers! Prior to this function call, the plugin pointers (such as g_carbFramework or g_carbLogging) have not been initialized.