module.h

Go to the documentation of this file.

/* Copyright, 2001 Nevrax Ltd.
 *
 * This file is part of NEVRAX NEL.
 * NEVRAX NEL is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.

 * NEVRAX NEL is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License for more details.

 * You should have received a copy of the GNU General Public License
 * along with NEVRAX NEL; see the file COPYING. If not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */


#ifndef NL_FILE_MODULE_H
#define NL_FILE_MODULE_H

#include "nel/misc/factory.h"
#include "nel/misc/command.h"
#include "nel/misc/string_mapper.h"
#include "nel/misc/co_task.h"
#include "nel/misc/algo.h"
#include "nel/net/message.h"
#include "nel/net/unified_network.h"
#include "module_common.h"

namespace NLNET
{
    class CGatewayRoute;
    class IModuleInterceptable;

    class IInterceptorRegistrar
    {
    public:
        virtual ~IInterceptorRegistrar() { }
        virtual void registerInterceptor(IModuleInterceptable *interceptor) =0;
        virtual void unregisterInterceptor(IModuleInterceptable *interceptor) =0;
    };

    class IModuleInterceptable
    {
    public:
        IModuleInterceptable();
        virtual ~IModuleInterceptable();

        void registerInterceptor(IInterceptorRegistrar *registrar);

        void interceptorUnregistered(IInterceptorRegistrar *registrar);

        IInterceptorRegistrar *getRegistrar();

        virtual std::string         buildModuleManifest() const { return std::string(); }

        //@name Callback from module sockets

        virtual void                onModuleUp(IModuleProxy *moduleProxy) = 0;
        virtual void                onModuleDown(IModuleProxy *moduleProxy) =0;
        virtual bool                onProcessModuleMessage(IModuleProxy *senderModuleProxy, const CMessage &message) =0;
        virtual void                onModuleSecurityChange(IModuleProxy *moduleProxy) =0;

    private:
        IInterceptorRegistrar       *_Registrar;
    };

    class IModule :
        public NLMISC::CRefCount,
        public IInterceptorRegistrar,
        public IModuleInterceptable
    {
        friend class IModuleFactory;

        virtual void setFactory(IModuleFactory *factory) =0;

    public:
        class EModuleAlreadyPluggedHere : public NLMISC::Exception
        {
        };

        class EInvokeFailed : public NLMISC::Exception
        {
        };

        class EInvokeBadReturn : public NLMISC::Exception
        {
        };

        // Module management =====================

        virtual ~IModule() {}

        virtual bool            initModule(const TParsedCommandLine &initInfo) =0;

        //@name Basic module information

        virtual TModuleId           getModuleId() const =0;
        virtual const std::string   &getModuleName() const =0;
        virtual const std::string   &getModuleClassName() const =0;
        virtual const std::string   &getModuleFullyQualifiedName() const =0;

        virtual std::string getModuleManifest() const =0;

        virtual bool isImmediateDispatchingSupported() const { return true; }

        //@name Callback from the module manager

        virtual void                onServiceUp(const std::string &serviceName, NLNET::TServiceId serviceId) =0;
        virtual void                onServiceDown(const std::string &serviceName, NLNET::TServiceId serviceId) = 0;
        virtual void                onModuleUpdate() =0;
        virtual void                onApplicationExit() = 0;

        // socket management =====================

        //@name module sockets operation

        virtual void                plugModule(IModuleSocket *moduleSocket)
            throw (EModuleAlreadyPluggedHere)
            =0;
        virtual void                unplugModule(IModuleSocket *moduleSocket)
            throw (EModuleNotPluggedHere)
            =0;
        virtual void                getPluggedSocketList(std::vector<IModuleSocket*> &resultList) =0;


        //@name Callback from module sockets

//      virtual void                onModuleUp(IModuleProxy *moduleProxy) = 0;
//      virtual void                onModuleDown(IModuleProxy *moduleProxy) =0;
        virtual void                onReceiveModuleMessage(IModuleProxy *senderModuleProxy, const CMessage &message) =0;
//      virtual void                onProcessModuleMessage(IModuleProxy *senderModuleProxy, const CMessage &message) =0;
//      virtual void                onModuleSecurityChange(IModuleProxy *moduleProxy) =0;

        virtual void        invokeModuleOperation(IModuleProxy *destModule, const NLNET::CMessage &opMsg, NLNET::CMessage &resultMsg)
            throw (EInvokeFailed)
            =0;


        //@name Callback from module sockets management
        enum TModuleSocketEvent
        {
            mse_plugged,
            mse_before_unplug,
            mse_unplugged,
        };
        virtual void    onModuleSocketEvent(IModuleSocket *moduleSocket, TModuleSocketEvent eventType) =0;


        //@name internal method, should not be used by client code
        virtual void _onModuleUp(IModuleProxy *removedProxy) =0;
        virtual void _onModuleDown(IModuleProxy *removedProxy) =0;


    };

    const TModulePtr        NullModule;



    struct TSecurityData
    {
        // for factory system
        struct TCtorParam
        {
            uint8   DataTag;

            TCtorParam(uint8 dataTag)
                :   DataTag(dataTag)
            {
            }
        };
        uint8           DataTag;

        TSecurityData   *NextItem;

        TSecurityData(const TCtorParam &params)
            : DataTag(params.DataTag),
            NextItem(NULL)

        {
        }

        virtual ~TSecurityData()
        {
            if (NextItem != NULL)
                delete NextItem;
        }

        virtual void serial(NLMISC::CMemStream &s) =0;

    };

    struct TUnknownSecurityData : public TSecurityData
    {
        uint8               RealDataTag;
        std::vector<uint8>  Data;

        TUnknownSecurityData(uint8 realDataTag, uint32 size)
            : TSecurityData(TSecurityData::TCtorParam(0xff)),
            RealDataTag(realDataTag),
            Data(size)
        {
        }

        void serial(NLMISC::CMemStream &s)
        {
            for (uint i=0; i<Data.size(); ++i)
            {
                s.serial(Data[i]);
            }
        }
    };

//  NLMISC_REGISTER_OBJECT(TSecurityData, TUnknownSecurityData, uint8, 0xff);

    class IModuleProxy : public NLMISC::CRefCount
    {
    public:
        virtual ~IModuleProxy() {}

        virtual TModuleId       getModuleProxyId() const =0;

        virtual TModuleId       getForeignModuleId() const =0;

        virtual uint32              getModuleDistance() const =0;

        virtual IModule             *getLocalModule() const =0;

        virtual CGatewayRoute       *getGatewayRoute() const =0;

        virtual const std::string &getModuleName() const =0;
        virtual const std::string &getModuleClassName() const =0;
        virtual const std::string &getModuleManifest() const =0;

        virtual IModuleGateway *getModuleGateway() const =0;

        virtual void        sendModuleMessage(IModule *senderModule, const NLNET::CMessage &message)
            throw (EModuleNotReachable)
            =0;

        virtual const TSecurityData *getFirstSecurityData() const = 0;

        virtual const TSecurityData *findSecurityData(uint8 dataTag) const =0;
    };

    const TModuleProxyPtr   NullModuleProxy;

    class CModuleTask : public NLMISC::CCoTask
    {
        bool    _FailInvoke;
    protected:
        CModuleTask (class CModuleBase *module);

        void initMessageQueue(class CModuleBase *module);

        // A module having a module task always running MUST call this evenly to
        // process message received by the module.
        void flushMessageQueue(class CModuleBase *module);

    public:
        // for task blocked in 'invoke' to fail with an exception
        void failInvoke()
        {
            _FailInvoke = true;
        }

        bool mustFailInvoke()
        {
            return _FailInvoke;
        }

        void resetFailInvoke()
        {
            _FailInvoke = false;
        }

        void processPendingMessage(class CModuleBase *module);
    };

    template <class T>
    class TModuleTask : public CModuleTask
    {
    public:

        typedef void (T::*TMethodPtr)();

    private:
        T           *_Module;
        TMethodPtr  _TaskMethod;

        // override CTask::run
        void run()
        {
            initMessageQueue(_Module);

            try
            {
                // run the module task command control to module task method
                (_Module->*_TaskMethod)();
            }
            catch (NLMISC::Exception e)
            {
                nlwarning("In module task '%s', exception '%e' thrown", typeid(this).name(), e.what());
            }
            catch (...)
            {
                nlwarning("In module task '%s', unknown exception thrown", typeid(this).name());
            }

            // finish the dispatch
            flushMessageQueue(_Module);
        }
    public:

        TModuleTask(T *module,  void (T::*taskMethod)())
            :   CModuleTask(module),
                _Module(module),
                _TaskMethod(taskMethod)
        {
        }
    };

    // a special macro for easy module task startup
#define NLNET_START_MODULE_TASK(className, methodName) \
    { \
        TModuleTask<className> *task = new TModuleTask<className>(this, &className::methodName); \
        queueModuleTask(task); \
    } \


    class IModuleFactory : public NLMISC::CRefCount
    {
    protected:
        std::string             _ModuleClassName;
        std::set<TModulePtr>    _ModuleInstances;
    public:


        IModuleFactory(const std::string &moduleClassName);

        virtual const std::string &getModuleClassName() const;
        virtual const std::string &getInitStringHelp() const =0;

        virtual IModule *createModule() =0;

        virtual void    deleteModule(IModule *module);

        virtual ~IModuleFactory();

        void registerModuleInFactory(TModulePtr module);
    };

//  const TModuleFactoryPtr NullModuleFactory;

    template <class moduleClass>
    class CModuleFactory : public IModuleFactory
    {
    public:
        CModuleFactory(const std::string &moduleClassName)
            : IModuleFactory(moduleClassName)
        {}

        virtual IModule *createModule()
        {
            IModule *module = new moduleClass;
            registerModuleInFactory(module);
            return module;
        }

        virtual const std::string &getInitStringHelp() const
        {
            return moduleClass::getInitStringHelp();
        }

    };

#define NLNET_REGISTER_MODULE_FACTORY(moduleClassName, registrationName) \
    class moduleClassName##Factory : public NLNET::CModuleFactory<moduleClassName> \
    { \
    public: \
        static const std::string &theModuleClassName() \
        { \
            static const std::string name(registrationName); \
            return name; \
        } \
        \
        moduleClassName##Factory() \
            : NLNET::CModuleFactory<moduleClassName>(theModuleClassName()) \
        {} \
    };\
    NLMISC_REGISTER_OBJECT_INDIRECT(NLNET::IModuleFactory, moduleClassName##Factory, std::string, registrationName)


//#define NLNET_MAKE_MODULE_FACTORY_TYPENAME(moduleClassName) moduleClassName##Factory

#define NLNET_GET_MODULE_FACTORY(moduleClassName)   moduleClassName##Factory

    class CModuleSocket;

    class CModuleBase : public IModule, public NLMISC::ICommandsHandler
    {
        // Module manager is our friend coz it need to feed some field here
        friend class CModuleManager;
        friend class CModuleTask;

        typedef std::set<IModuleSocket *>   TModuleSockets;
        TModuleSockets          _ModuleSockets;

        typedef std::list<IModuleInterceptable*>    TInterceptors;
        TInterceptors           _ModuleInterceptors;

        //@name Synchronous messaging
        typedef std::list<std::pair<IModuleProxy *, CMessage> > TMessageList;
        TMessageList            _SyncMessages;
        typedef std::list<CModuleTask*> TModuleTasks;
        TModuleTasks            _ModuleTasks;

        typedef std::vector<IModuleProxy*>  TInvokeStack;
        TInvokeStack            _InvokeStack;

        IModuleProxy            *_CurrentSender;
        const NLNET::CMessage   *_CurrentMessage;
        bool                    _CurrentMessageFailed;

        CModuleTask             *_MessageDispatchTask;

        virtual void setFactory(IModuleFactory *factory);
        virtual IModuleFactory *getFactory();
    protected:
        IModuleFactory      *_ModuleFactory;
        TModuleId           _ModuleId;
        std::string         _ModuleName;
        mutable std::string _FullyQualifedModuleName;


        CModuleBase();
        ~CModuleBase();

        virtual void registerInterceptor(IModuleInterceptable *interceptor);
        virtual void unregisterInterceptor(IModuleInterceptable *interceptor);

        const std::string   &getCommandHandlerName() const;
        TModuleId           getModuleId() const;
        const std::string   &getModuleName() const;

        const std::string   &getModuleClassName() const;

        const std::string   &getModuleFullyQualifiedName() const;

        std::string         getModuleManifest() const;

        virtual void        onReceiveModuleMessage(IModuleProxy *senderModuleProxy, const CMessage &message);

        void _receiveModuleMessageTask();

        void queueModuleTask(CModuleTask *task);

        CModuleTask *getActiveModuleTask();

    public:
        static const std::string &getInitStringHelp();

        template <class T>
        T *getInterceptor(T *dummy, IModuleInterceptable *previous = NULL)
        {
            TInterceptors::iterator it(_ModuleInterceptors.begin());
            if (previous != NULL)
            {
                // advance up to next the previous
                while (it != _ModuleInterceptors.end() && *it != previous)
                    ++it;
                if (it != _ModuleInterceptors.end())
                    ++it;
            }

            while (it != _ModuleInterceptors.end())
            {
                IModuleInterceptable *mi = *it;
                T *inter = dynamic_cast<T*>(mi);

                if (inter != NULL)
                {
                    dummy = inter;
                    return inter;
                }

                ++it;
            }

            dummy = NULL;
            return NULL;
        }
    protected:
        // Init base module, init module name
        bool                initModule(const TParsedCommandLine &initInfo);

        void                plugModule(IModuleSocket *moduleSocket) throw (EModuleAlreadyPluggedHere);
        void                unplugModule(IModuleSocket *moduleSocket)  throw (EModuleNotPluggedHere);
        void                getPluggedSocketList(std::vector<IModuleSocket*> &resultList);
        void                invokeModuleOperation(IModuleProxy *destModule, const NLNET::CMessage &opMsg, NLNET::CMessage &resultMsg) throw (EInvokeFailed);
        void                _onModuleUp(IModuleProxy *removedProxy);
        void                _onModuleDown(IModuleProxy *removedProxy);

        bool                _onProcessModuleMessage(IModuleProxy *senderModuleProxy, const CMessage &message);




        NLMISC_COMMAND_HANDLER_TABLE_BEGIN(CModuleBase)
            NLMISC_COMMAND_HANDLER_ADD(CModuleBase, dump, "display informations about module instance status", "no args")
            NLMISC_COMMAND_HANDLER_ADD(CModuleBase, plug, "plug the module in a module socket", "<socket_name>")
            NLMISC_COMMAND_HANDLER_ADD(CModuleBase, unplug, "unplug the module out of a module socket", "<socket_name>")
            NLMISC_COMMAND_HANDLER_ADD(CModuleBase, sendPing, "send a ping message to another module using the first available route", "<addresseeModuleName>")
        NLMISC_COMMAND_HANDLER_TABLE_END

        NLMISC_CLASS_COMMAND_DECL(dump);
        NLMISC_CLASS_COMMAND_DECL(plug);
        NLMISC_CLASS_COMMAND_DECL(unplug);
        NLMISC_CLASS_COMMAND_DECL(sendPing);
    };

    class CGatewayRoute;

    class CModuleProxy : public IModuleProxy
    {
        friend class CModuleManager;
        friend class CStandardGateway;

        IModuleGateway      *_Gateway;
        CGatewayRoute       *_Route;
        uint32              _Distance;
        TModuleId           _ModuleProxyId;
        TModuleId           _ForeignModuleId;

        TModulePtr          _LocalModule;
        NLMISC::TStringId   _ModuleClassName;
        NLMISC::TStringId   _FullyQualifiedModuleName;
        std::string         _Manifest;
        TSecurityData       *_SecurityData;

        CModuleProxy(TModulePtr localModule, TModuleId localModuleId, const std::string &moduleClassName, const std::string &fullyQualifiedModuleName, const std::string &moduleManifest);
    public:

        const CGatewayRoute * getRoute() const
        {
            return _Route;
        }

        virtual TModuleId   getModuleProxyId() const;

        virtual TModuleId   getForeignModuleId() const;


        uint32              getModuleDistance() const;

        IModule             *getLocalModule() const;

        CGatewayRoute       *getGatewayRoute() const;

        virtual const std::string &getModuleName() const;
        virtual const std::string &getModuleClassName() const;
        virtual const std::string &getModuleManifest() const;

        virtual IModuleGateway *getModuleGateway() const;

        virtual void        sendModuleMessage(IModule *senderModule, const NLNET::CMessage &message)
            throw (EModuleNotReachable);

        virtual const TSecurityData *getFirstSecurityData() const
        {
            return _SecurityData;
        }

        virtual const TSecurityData *findSecurityData(uint8 dataTag) const;
    };



    template <class PtrContainer>
    class TBroadcastModuleMessage
    {

        void sendMessage(IModule *sender, const PtrContainer &addresseeProxies, const NLNET::CMessage &message)
        {
            typename PtrContainer::iterator first(addresseeProxies.begin()), last(addresseeProxies.end());
            for (; first != last; ++first)
            {
                IModuleProxy *proxy = static_cast<IModuleProxy*>(*first);

                proxy->sendModuleMessage(sender, message);
            }
        }
    };


} // namespace NLNET

#endif // NL_FILE_MODULE_H