From c47b953a2725986aaeb4798aab4ebad54191e6ab Mon Sep 17 00:00:00 2001 From: NotAdam Date: Tue, 24 Jul 2018 22:48:42 +1000 Subject: [PATCH] some more documentation --- .../sapphire_zone/Script/NativeScriptMgr.h | 70 ++++++++++++++++++- src/servers/sapphire_zone/Script/ScriptInfo.h | 31 ++++++++ .../sapphire_zone/Script/ScriptLoader.h | 5 +- src/servers/sapphire_zone/Script/ScriptMgr.h | 26 +++++-- 4 files changed, 125 insertions(+), 7 deletions(-) diff --git a/src/servers/sapphire_zone/Script/NativeScriptMgr.h b/src/servers/sapphire_zone/Script/NativeScriptMgr.h index 9445bb56..04436a31 100644 --- a/src/servers/sapphire_zone/Script/NativeScriptMgr.h +++ b/src/servers/sapphire_zone/Script/NativeScriptMgr.h @@ -13,30 +13,93 @@ namespace Core { namespace Scripting { + /*! + * @brief Contains all the functionality for easily loading, unloading, reloading and generally accessing scripts. + */ class NativeScriptMgr { protected: + /*! + * @brief An internal list that maps script types to another list containing scripts indexed by their assoicated id + */ std::unordered_map< std::size_t, std::unordered_map< uint32_t, ScriptObject* > > m_scripts; + ScriptLoader m_loader; + /*! + * @brief The queue that scripts to be reloaded are placed into. + */ std::queue< std::string > m_scriptLoadQueue; + /*! + * Used to unload a script, clears m_scripts of any scripts assoicated with a ScriptInfo and then unloads that module + * @param info A pointer to the ScriptInfo object that is to be erased + * @return true if successful, false if not + */ bool unloadScript( ScriptInfo* info ); public: - NativeScriptMgr( ) = default; + NativeScriptMgr() = default; + /*! + * @brief Loads a script from a path + * + * This will populate m_scripts if it is successful and scripts will be available as soon as this returns. + * + * @param path The path to the module to load + * @return true if successful, false if not + */ bool loadScript( const std::string& path ); + + /*! + * @brief Unloads a script + * @param name The module name of the script to unload + * @return true if successful + */ bool unloadScript( const std::string& name ); + + /*! + * @brief Queues a script module to be reloaded + * + * Due to the nature of how this works, there's no return. + * It will just silently fail over and over again to infinity and beyond until the server restarts... not that should ever happen under normal circumstances. + * + * @param name The name of the module to be reloaded. + */ void queueScriptReload( const std::string& name ); + + /*! + * @brief Case-insensitive search for modules, useful for debug commands + * @param scripts a set of ScriptInfo ptrs + * @param search the search term + */ void findScripts( std::set< Core::Scripting::ScriptInfo* >& scripts, const std::string& search ); + /*! + * Called on a regular interval, allows for scripts to be loaded from the internal load queue. + */ void processLoadQueue(); + /*! + * Gets the module file extention for the current platform (windows, linux, osx) + * @return The file extension for the current platform + */ const std::string getModuleExtension(); + + /*! + * Checks to see if a module with the specified name exists + * @param name The module name to lookup + * @return true if loaded, false if not + */ bool isModuleLoaded( const std::string& name ); + /*! + * Get a specific script from the internal table + * @tparam T The type of the script to search for + * @param scriptId The ID of the script to search for + * @return T* if successful, nullptr if the script doesn't exist + */ template< typename T > T* getScript( uint32_t scriptId ) { @@ -51,7 +114,10 @@ namespace Scripting { }; - + /*! + * Creates an instance of NativeScriptMgr + * @return a boost::shared_ptr to NativeScriptMgr + */ boost::shared_ptr< NativeScriptMgr > createNativeScriptMgr(); } } diff --git a/src/servers/sapphire_zone/Script/ScriptInfo.h b/src/servers/sapphire_zone/Script/ScriptInfo.h index c4ebae08..3523d16b 100644 --- a/src/servers/sapphire_zone/Script/ScriptInfo.h +++ b/src/servers/sapphire_zone/Script/ScriptInfo.h @@ -16,16 +16,47 @@ typedef void* ModuleHandle; namespace Core { namespace Scripting { + /*! + * An internal class used to track information about loaded modules and their scripts. + * The main purpose of this is to maintain easy access to the module handle and the pointers to scripts that are loaded. + * Furthermore, allows for quick and easy cross platform access to the module paths associated with the runtime module cache and its original path. + */ class ScriptInfo { public: ScriptInfo() = default; + /*! + * @brief The file name of the loaded library. + * + * On all platforms, this will be the full filename of the module, eg: + * - script_instances.dll on Windows + * - libscript_instances.so on Linux + */ std::string library_name; + + /*! + * The path to the module currently loaded in memory from the cached location. + */ std::string cache_path; + + /*! + * The original path of the module before it was copied to the cache location. + */ std::string library_path; + /*! + * @brief A handle to the module. + * + * The underlying type for this depends on platform. On Windows it's some stupid shit, on everything else it's a void*. + */ ModuleHandle handle; + + /*! + * @An internal list of all the pointers to each ScriptObject + * + * This is tracked so when we unload this module we can call delete on each ScriptObject and correctly free it from memory. + */ std::vector< ScriptObject* > scripts; }; } diff --git a/src/servers/sapphire_zone/Script/ScriptLoader.h b/src/servers/sapphire_zone/Script/ScriptLoader.h index c031057b..a3bc2a2c 100644 --- a/src/servers/sapphire_zone/Script/ScriptLoader.h +++ b/src/servers/sapphire_zone/Script/ScriptLoader.h @@ -47,7 +47,10 @@ namespace Scripting { const std::string getModuleExtension(); /*! - * Load a module from a path + * @brief Load a module from a path + * + * Internally, this will also copy the module from it's original folder into the cache folder. + * * @return A pointer to ScriptInfo if the load was successful, nullptr if it failed */ ScriptInfo* loadModule( const std::string& ); diff --git a/src/servers/sapphire_zone/Script/ScriptMgr.h b/src/servers/sapphire_zone/Script/ScriptMgr.h index 4af842bf..adffb510 100644 --- a/src/servers/sapphire_zone/Script/ScriptMgr.h +++ b/src/servers/sapphire_zone/Script/ScriptMgr.h @@ -16,23 +16,41 @@ namespace Core class ScriptMgr { private: - - boost::shared_ptr< NativeScriptMgr > m_nativeScriptMgr; + /*! + * A shared ptr to NativeScriptMgr, used for accessing and managing the native script system. + */ + boost::shared_ptr< NativeScriptMgr > m_nativeScriptMgr; std::function< std::string( Entity::Player& ) > m_onFirstEnterWorld; - // auto fn = m_pChaiHandler->eval< std::function >( "onFirstEnterWorld" ); + /*! + * Used to ignore the first change notification that Watchdog emits. + * Because reasons, it likes to emit an initial notification with all the files that match the filter, we don't want that so we ignore it. + */ bool m_firstScriptChangeNotificiation; public: ScriptMgr(); ~ScriptMgr(); + /*! + * @brief Loads all the script modules and readies the ScriptMgr + * + * This gets all the modules inside the specified scripts folder and then attempts to load each one. + * After that, it starts the directory watcher so the server can reload modules at runtime when changes occur. + * + * @return true if init success + */ bool init(); - void reload(); + /*! + * Called on each tick or at a regular interval. Allows for the NativeScriptMgr to process module loading and reloading. + */ void update(); + /*! + * Registers a directory watcher which allows for script modules to be reloaded when changes to the modules occur + */ void watchDirectories(); void onPlayerFirstEnterWorld( Entity::Player& player );