ezEngine  Milestone 7
ezPlugin Class Reference

ezPlugin allows to manage all dynamically loadable plugins. Each plugin DLL must contain one global instance of ezPlugin. More...

#include <Plugin.h>

Inheritance diagram for ezPlugin:

Classes

struct  PluginEvent
 The data that is broadcast whenever a plugin is (un-) loaded. More...
 

Public Types

typedef void(* OnPluginLoadedFunction )(bool bReloading)
 Callback type for when a plugin has just been loaded (not yet initialized). bReloading is true, if the plugin is currently being reloaded.
 
typedef void(* OnPluginUnloadedFunction )(bool bReloading)
 Callback type for when a plugin will be unloaded (after all deinitializations). bReloading is true, if the plugin is currently being reloaded.
 

Public Member Functions

 ezPlugin (bool bIsReloadable, OnPluginLoadedFunction OnLoadPlugin=nullptr, OnPluginUnloadedFunction OnUnloadPlugin=nullptr, const char *szPluginDependency1=nullptr, const char *szPluginDependency2=nullptr, const char *szPluginDependency3=nullptr, const char *szPluginDependency4=nullptr, const char *szPluginDependency5=nullptr)
 Creates a new plugin object. More...
 
const char * GetPluginName () const
 Returns the name that was used to load the plugin from disk.
 
bool IsReloadable () const
 Returns whether this plugin supports hot-reloading.
 
const char * GetPluginDependency (ezUInt8 uiDependency) const
 Returns the n-th plugin that this one is dependent on, or nullptr if there is no further dependency.
 

Static Public Member Functions

static void BeginPluginChanges ()
 Call this before loading / unloading several plugins in a row, to prevent unnecessary re-initializations.
 
static void EndPluginChanges ()
 Must be called to finish what BeginPluginChanges started.
 
static ezResult LoadPlugin (const char *szPluginFile)
 Tries to load a DLL dynamically into the program. More...
 
static ezResult UnloadPlugin (const char *szPluginFile)
 Tries to unload a previously loaded plugin. More...
 
static ezResult ReloadPlugins (bool bForceReload=false)
 Hot-reloads all plugins that are marked as reloadable. More...
 
static ezPluginFindPluginByName (const char *szPluginName)
 Tries to find an ezPlugin instance by the given name. Returns nullptr if there is no such plugin. Can be used to check whether a certain plugin is loaded.
 
static void SetMaxParallelInstances (ezUInt32 uiMaxParallelInstances)
 Sets how many tries the system will do to find a free plugin file name. More...
 

Static Public Attributes

static ezEvent< const
PluginEvent & > 
s_PluginEvents
 Code that needs to be execute whenever a plugin is loaded or unloaded can register itself here to be notified of such events.
 

Private Member Functions

 EZ_DECLARE_ENUMERABLE_CLASS (ezPlugin)
 
void Initialize (bool bReloading)
 
void Uninitialize (bool bReloading)
 

Static Private Member Functions

static void GetPluginPaths (const char *szPluginName, ezStringBuilder &sOldPath, ezStringBuilder &sNewPath, ezUInt8 uiFileNumber)
 
static ezResult UnloadPluginInternal (const char *szPlugin, bool bReloading)
 
static ezResult LoadPluginInternal (const char *szPlugin, bool bLoadCopy, bool bReloading)
 
static void SortPluginReloadOrder (ezHybridArray< ezString, 16 > &PluginsToReload)
 

Private Attributes

const char * m_szPluginDependencies [5]
 
ezString m_sLoadedFromFile
 
OnPluginLoadedFunction m_OnLoadPlugin
 
OnPluginUnloadedFunction m_OnUnloadPlugin
 
bool m_bInitialized
 
bool m_bIsReloadable
 

Static Private Attributes

static ezUInt32 m_uiMaxParallelInstances = 32
 
static ezInt32 s_iPluginChangeRecursionCounter = 0
 

Additional Inherited Members

- Protected Attributes inherited from ezEnumerable< ezPlugin >
ezEnumerablem_pNextInstance
 

Detailed Description

ezPlugin allows to manage all dynamically loadable plugins. Each plugin DLL must contain one global instance of ezPlugin.

Put a global instance of ezPlugin somewhere into the source of each dynamic plugin DLL. Certain code depends on such instances to work correctly with dynamically loaded code. For example ezStartup allows to initialize and deinitialize code from dynamic DLLs properly (and in the correct order), by listening to events from ezPlugin. ezPlugin also provides static functions to load and unload DLLs.

Constructor & Destructor Documentation

ezPlugin::ezPlugin ( bool  bIsReloadable,
OnPluginLoadedFunction  OnLoadPlugin = nullptr,
OnPluginUnloadedFunction  OnUnloadPlugin = nullptr,
const char *  szPluginDependency1 = nullptr,
const char *  szPluginDependency2 = nullptr,
const char *  szPluginDependency3 = nullptr,
const char *  szPluginDependency4 = nullptr,
const char *  szPluginDependency5 = nullptr 
)

Creates a new plugin object.

Parameters
bIsReloadableIf set to true, 'ReloadPlugins' will reload this plugin (if it was modified).
OnLoadPluginWill be called right after the plugin is loaded, even before other code is notified of that the plugin is now loaded.
OnUnloadPluginWill be called shortly before the DLL is finally unloaded. All other code has already been notified that the plugin is being unloaded.
szPluginDependency1Allows to specify other modules that this plugin depends on. These will be automatically loaded and unloaded together with this plugin.

Member Function Documentation

ezResult ezPlugin::LoadPlugin ( const char *  szPluginFile)
static

Tries to load a DLL dynamically into the program.

For every time a plugin is loaded via 'LoadPlugin' it should also get unloaded via 'UnloadPlugin', as ezPlugin counts these and only unloads a plugin once its reference count reaches zero.

EZ_SUCCESS is returned when the DLL is either successfully loaded or has already been loaded before. EZ_FAILURE is returned if the DLL cannot be located or it could not be loaded properly.

ezResult ezPlugin::ReloadPlugins ( bool  bForceReload = false)
static

Hot-reloads all plugins that are marked as reloadable.

Returns failure or success depending on whether (un-)loading of any of the hot-reloadable plugins failed. Even if one fails, it still tries to reload ALL plugins. If a reloadable plugin does not exist (anymore), that plugin is not even tried to be reloaded. If a plugin can be unloaded but reloading fails, a backup of the previous version is used instead. In case that fails as well, the application will probably crash. EZ_FAILURE is returned if anything could not be reloaded as desired, independent of whether the system was able to recover from it. So 'failure' means that not all reloadable code has been updated.

static void ezPlugin::SetMaxParallelInstances ( ezUInt32  uiMaxParallelInstances)
static

Sets how many tries the system will do to find a free plugin file name.

During plugin loading the system creates copies of the plugin DLLs for reloading. This only works if the system can find a file to write to. If too many instances of the engine are running, no such free file name might be found and plugin loading fails. This value specifies how often the system tries to find a free file. The default is 32.

ezResult ezPlugin::UnloadPlugin ( const char *  szPluginFile)
static

Tries to unload a previously loaded plugin.

For every time a plugin is loaded via 'LoadPlugin' it should also get unloaded via 'UnloadPlugin', as ezPlugin counts these and only unloads a plugin once its reference count reaches zero. If a plugin is not unloaded, because its refcount has not yet reached zero, 'UnloadPlugin' still returns EZ_SUCCESS.

EZ_SUCCESS is returned when the DLL is either successfully unloaded are has already been unloaded before (or has even never been loaded before). EZ_FAILURE is returned if the DLL cannot be unloaded (at this time).


The documentation for this class was generated from the following files: