carbOnPluginStartupEx

bool carbOnPluginStartupEx()

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 supersedes carbOnPluginStartup. The main difference is that this function allows the plugin to indicate if startup fails (such as if a required subsystem fails to start) and allow the Framework to fail acquiring an interface gracefully. If this function does not exist, carbOnPluginStartup 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 successfully, the Framework considers your plugin as initialized. If this function reports failure, the plugin will be unloaded but remain registered. Attempting to acquire an interface from this plugin in the future will reload the plugin and attempt to call this function again.

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::OnPluginStartupExFn and named kCarbOnPluginStartupExFnName.

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 carbOnPluginStartupEx 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.

Returns: true if the plugin started successfully; false otherwise.