imodule.h

#pragma once

#include <memory>
#include <functional>
#include <cassert>
#include <sigc++/trackable.h>
#include <sigc++/signal.h>
#include <mutex>
#include <stdexcept>

#include <string>
#include <set>
#include <vector>

#include "itextstream.h"

/**
 * \defgroup module Module system
 */

/** greebo: These registry keys can be used application-wide during runtime
 *          to retrieve the various paths.
 */
const char* const RKEY_APP_PATH = "user/paths/appPath";
const char* const RKEY_SETTINGS_PATH = "user/paths/settingsPath";
const char* const RKEY_BITMAPS_PATH = "user/paths/bitmapsPath";
const char* const RKEY_MAP_PATH = "user/paths/mapPath";
const char* const RKEY_PREFAB_PATH = "user/paths/prefabPath";

/**
 * greebo: Compatibility level: a number inlined into all the modules and returned 
 * by their RegisterableModule::getCompatibilityLevel() method.
 *
 * This number should be changed each time the set of module/plugin files (.so/.dll/.dylib) 
 * is modified, especially when files are going to be removed from a DarkRadiant release.
 * The number will be checked by the ModuleRegistry against the internally stored one
 * to detect outdated binaries and reject their registration.
 *
 * As long as no external module/plugin files are removed this number is safe to stay 
 * as it is. Keep this number compatible to std::size_t, i.e. unsigned.
 */
#define MODULE_COMPATIBILITY_LEVEL 20200419

// A function taking an error title and an error message string, invoked in debug builds
// for things like ASSERT_MESSAGE and ERROR_MESSAGE
typedef std::function<void (const std::string&, const std::string&)> ErrorHandlingFunction;

// This method holds a function pointer which can do some error display (like popups)
// Each module binary has its own copy of this, it's initialised in performDefaultInitialisation()
inline ErrorHandlingFunction& GlobalErrorHandler()
{
    static ErrorHandlingFunction _func;
    return _func;
}

/**
 * Provider for various information that may be required by modules during
 * initialisation.
 *
 * \ingroup module
 */
class ApplicationContext
{
public:

    /**
     * \brief
     * Argument list type.
     */
    typedef std::vector<std::string> ArgumentList;

    /// Destructor
    virtual ~ApplicationContext() {}

    /// Return the path to the installed application
    virtual std::string getApplicationPath() const = 0;

    /**
     * Return the application library path, containing modules and plugins.
     *
     * On Windows this is most likely the same as the application path. On
     * Linux it might be a hard-coded path like /usr/lib/darkradiant, or a
     * relocatable relative path like ../lib
     */
    virtual std::string getLibraryPath() const = 0;

    /**
     * Return the toplevel path contaning runtime data files, such as the GL
     * programs or UI descriptor files. On Windows this is the same as the
     * application path, on Linux it is determined at compile-time but probably
     * something like /usr/share/darkradiant.
     */
    virtual std::string getRuntimeDataPath() const = 0;

    /// Return the directory containing user settings (user.xml and friends)
    virtual std::string getSettingsPath() const = 0;

    /// Return the directory for temporary output files, such as logs
    virtual std::string getCacheDataPath() const = 0;

    /// Return the directory containing UI bitmaps
    virtual std::string getBitmapsPath() const = 0;

    /// Return the path to HTML documentation files
    virtual std::string getHTMLPath() const = 0;

    /**
     * \brief
     * Return the list of command line arguments.
     */
    virtual const ArgumentList& getCmdLineArgs() const = 0;

    /**
     * Return the reference to the application's output/error streams.
     */
    virtual std::ostream& getOutputStream() const = 0;
    virtual std::ostream& getErrorStream() const = 0;
    virtual std::ostream& getWarningStream() const = 0;

    // Provides a single mutex object which should be locked by client code
    // before writing to the any of the above streams.
    virtual std::mutex& getStreamLock() const = 0;

    /**
     * Sets up the paths and stores them into the registry.
     */
    virtual void savePathsToRegistry() const = 0;

    /**
     * Retrieve a function pointer which can handle assertions and runtime errors
     */
    virtual const ErrorHandlingFunction& getErrorHandlingFunction() const = 0;
};

/**
 * Set of strings for module dependencies.
 */
typedef std::set<std::string> StringSet;

/**
 * Interface class for modules. Each RegisterableModule can return its name and
 * its set of dependencies.
 *
 * Note that this interface does NOT concern itself with the type (interface)
 * of each individual module; it is up to the GlobalBlah() accessor function
 * associated with each module to perform the required downcast to the known
 * type.
 *
 * All RegisterableModules implement sigc::trackable, since they will often want
 * to connect themselves to another module's signal(s).
 *
 * \ingroup module
 */
class RegisterableModule: public sigc::trackable
{
private:
    const std::size_t _compatibilityLevel;

public:
    RegisterableModule() :
        _compatibilityLevel(MODULE_COMPATIBILITY_LEVEL)
    {}

    /**
     * Destructor
     */
    virtual ~RegisterableModule() {}

    /**
     * Return the name of this module. This must be globally unique across all
     * modules; the modulesystem will throw a logic_error if two modules attempt
     * to register themselves with the same name.
     */
    virtual const std::string& getName() const = 0;

    /**
     * Return the set of dependencies for this module. The return value is a
     * set of strings, each containing the unique name (as returned by
     * getName()) of a module which must be initialised before this one.
     */
    virtual const StringSet& getDependencies() const = 0;

    /**
     * Instruct this module to initialise itself. A RegisterableModule must NOT
     * invoke any calls to other modules in its constructor, since at the point
     * of construction the other modules will not have been initialised. Once
     * all of the dependencies are processed by the ModuleRegistry, each module
     * will have its initialiseModule() method called at the appropriate point.
     *
     * The ModuleRegistry guarantees that any modules named in the set of
     * dependencies returned by getDependencies() will be initialised and ready
     * for use at the time this method is invoked. Attempting to access a module
     * which was NOT listed as a dependency is undefined.
     *
     * @param ctx
     * The ApplicationContext of the running Radiant application.
     */
    virtual void initialiseModule(const ApplicationContext& ctx) = 0;

    /**
     * Optional shutdown routine. Allows the module to de-register itself,
     * shutdown windows, save stuff into the Registry and so on.
     *
     * All the modules are getting called one by one, all other modules
     * are available until the last shutdownModule() call was invoked.
     */
    virtual void shutdownModule() {
        // Empty default implementation
    }

    // Internally queried by the ModuleRegistry. To protect against leftover
    // binaries containing outdated moudles from being loaded and registered
    // the compatibility level is compared with the one in the ModuleRegistry.
    // Old modules with mismatching numbers will be rejected.
    // Function is intentionally non-virtual and inlined.
    std::size_t getCompatibilityLevel() const
    {
        return _compatibilityLevel;
    }
};

/**
 * Shared pointer typdef.
 */
typedef std::shared_ptr<RegisterableModule> RegisterableModulePtr;

/**
 * Interface for the module registry. This is the owner and manager of all
 * RegisterableModules defined in DLLs and the main binary.
 *
 * For obvious reasons, the ModuleRegistry itself is not a module, but a static
 * object owned by the main binary and returned through a globally-accessible
 * method.
 *
 * \ingroup module
 */
class IModuleRegistry 
{
public:
    /**
     * Destructor
     */
    virtual ~IModuleRegistry() {}

    /**
     * Register a RegisterableModule. The name and dependencies are retrieved
     * through the appropriate RegisterableModule interface methods.
     *
     * This method does not cause the RegisterableModule to be initialised.
     */
    virtual void registerModule(const RegisterableModulePtr& module) = 0;

    /**
     * Initialise all of the modules previously registered with
     * registerModule() in the order required by their dependencies. This method
     * is invoked once, at application startup, with any subsequent attempts
     * to invoke this method throwing a logic_error.
     */
    virtual void loadAndInitialiseModules() = 0;

    /**
     * All the RegisterableModule::shutdownModule() routines are getting
     * called one by one. No modules are actually destroyed during the
     * iteration is ongoing, so each module is guaranteed to exist.
     *
     * After the last shutdownModule() call has been invoked, the modules
     * can be safely unloaded/destroyed.
     */
    virtual void shutdownModules() = 0;

    /**
     * Retrieve the module associated with the provided unique name. If the
     * named module is not found, an empty RegisterableModulePtr is returned
     * (this allows modules to be optional).
     *
     * Note that the return value of this function is RegisterableModulePtr,
     * which in itself is useless to application code. It is up to the accessor
     * functions defined in each module interface (e.g. GlobalEntityCreator())
     * to downcast the pointer to the appropriate type.
     */
    virtual RegisterableModulePtr getModule(const std::string& name) const = 0;

    /**
     * Returns TRUE if the named module exists in the records.
     */
    virtual bool moduleExists(const std::string& name) const = 0;

    /**
     * This retrieves a reference to the information structure ApplicationContext,
     * which holds the AppPath, SettingsPath and references to the application
     * streams. The latter can be used by modules to initialise their
     * rMessage/globalErrorStreams().
     */
    virtual const ApplicationContext& getApplicationContext() const = 0;

    /**
     * Invoked when all modules have been initialised.
     */
    virtual sigc::signal<void> signal_allModulesInitialised() const = 0;

    /**
     * Progress function called during module loading and intialisation.
     * The string value will carry a message about what is currently in progress.
     * The float value passed to the signal indicates the overall progress and
     * will be in the range [0.0f..1.0f].
     */
    typedef sigc::signal<void, const std::string&, float> ProgressSignal;
    virtual ProgressSignal signal_moduleInitialisationProgress() const = 0;

    /**
    * Invoked when all modules have been shut down (i.e. after shutdownModule()).
    */
    virtual sigc::signal<void> signal_allModulesUninitialised() const = 0;

    // The compatibility level this Registry instance was compiled against.
    // Old module registrations will be rejected by the registry anyway,
    // on top of that they can actively query this number from the registry
    // to check whether they are being loaded into an incompatible binary.
    virtual std::size_t getCompatibilityLevel() const = 0;
};

namespace module
{
    /**
     * \namespace module
     * Types and functions implementing the module registry system.
     *
     * \ingroup module
     */

    /** greebo: This is a container holding a reference to the registry.
     *          The getRegistry() symbol above is not exported to the
     *          modules in Win32 compiles. That's why this structure
     *          has to be initialised in the RegisterModule() routine.
     *
     * As soon as it's initialised, the module can access the ModuleRegistry
     * with the routine GlobalModuleRegistry() below.
     */
    class RegistryReference {
        IModuleRegistry* _registry;
    public:
        RegistryReference() :
            _registry(NULL)
        {}

        inline void setRegistry(IModuleRegistry& registry) {
            _registry = &registry;
        }

        inline IModuleRegistry& getRegistry() {
            assert(_registry); // must not be NULL
            return *_registry;
        }

        static RegistryReference& Instance() {
            static RegistryReference _registryRef;
            return _registryRef;
        }
    };

    /**
     * Global accessor method for the ModuleRegistry.
     */
    inline IModuleRegistry& GlobalModuleRegistry() 
    {
        return RegistryReference::Instance().getRegistry();
    }

    // Exception thrown if the module being loaded is incompatible with the main binary
    class ModuleCompatibilityException : 
        public std::runtime_error
    {
    public:
        ModuleCompatibilityException(const std::string& msg) :
            std::runtime_error(msg)
        {}
    };

    // greebo: This should be called once by each module at load time to initialise
    // the OutputStreamHolders
    inline void initialiseStreams(const ApplicationContext& ctx)
    {
        GlobalOutputStream().setStream(ctx.getOutputStream());
        GlobalWarningStream().setStream(ctx.getWarningStream());
        GlobalErrorStream().setStream(ctx.getErrorStream());

#ifndef NDEBUG
        GlobalDebugStream().setStream(ctx.getOutputStream());
#endif

        // Set up the mutex for thread-safe logging
        GlobalOutputStream().setLock(ctx.getStreamLock());
        GlobalWarningStream().setLock(ctx.getStreamLock());
        GlobalErrorStream().setLock(ctx.getStreamLock());
        GlobalDebugStream().setLock(ctx.getStreamLock());
    }

    // Helper method initialising a few references and checking a module's
    // compatibility level with the one reported by the ModuleRegistry
    inline void performDefaultInitialisation(IModuleRegistry& registry)
    {
        if (registry.getCompatibilityLevel() != MODULE_COMPATIBILITY_LEVEL)
        {
            throw ModuleCompatibilityException("Compatibility level mismatch");
        }

        // Initialise the streams using the given application context
        initialiseStreams(registry.getApplicationContext());

        // Remember the reference to the ModuleRegistry
        RegistryReference::Instance().setRegistry(registry);

        // Set up the assertion handler
        GlobalErrorHandler() = registry.getApplicationContext().getErrorHandlingFunction();
    }
}

// Platform-specific definition which needs to be defined both
// in the plugins and the main binary.
#if defined(WIN32)
    #if defined(_MSC_VER)
        // In VC++ we use this to export symbols instead of using .def files
        // Note: don't use __stdcall since this is adding stack bytes to the function name
        #define DARKRADIANT_DLLEXPORT __declspec(dllexport)
    #else
        #define DARKRADIANT_DLLEXPORT 
    #endif
#elif defined(__APPLE__)
    #define DARKRADIANT_DLLEXPORT __attribute__((visibility("default")))
#else
    #define DARKRADIANT_DLLEXPORT
#endif