IForwardSys.h

Go to the documentation of this file.

#ifndef _INCLUDE_SOURCEMOD_FORWARDINTERFACE_H_
#define _INCLUDE_SOURCEMOD_FORWARDINTERFACE_H_

#include <IPluginSys.h>
#include <sp_vm_api.h>

using namespace SourcePawn;

#define SMINTERFACE_FORWARDMANAGER_NAME         "IForwardManager"
#define SMINTERFACE_FORWARDMANAGER_VERSION      3

/*
 * There is some very important documentation at the bottom of this file.
 * Readers interested in knowing more about the forward system, scrolling down is a must!
 */

namespace SourceMod
{
        enum ResultType
        {
                Pl_Continue = 0,        
                Pl_Changed = 1,         
                Pl_Handled = 3,         
                Pl_Stop = 4,            
        };

        enum ExecType
        {
                ET_Ignore = 0,          
                ET_Single = 1,          
                ET_Event = 2,           
                ET_Hook = 3,            
                ET_LowEvent = 4,        
        };
        
        #define SP_PARAMTYPE_ANY        0
        #define SP_PARAMFLAG_BYREF      (1<<0)
        #define SP_PARAMTYPE_CELL       (1<<1)
        #define SP_PARAMTYPE_FLOAT      (2<<1)
        #define SP_PARAMTYPE_STRING     (3<<1)|SP_PARAMFLAG_BYREF
        #define SP_PARAMTYPE_ARRAY      (4<<1)|SP_PARAMFLAG_BYREF
        #define SP_PARAMTYPE_VARARG     (5<<1)

        enum ParamType
        {
                Param_Any = SP_PARAMTYPE_ANY,                           
                Param_Cell = SP_PARAMTYPE_CELL,                         
                Param_Float = SP_PARAMTYPE_FLOAT,                       
                Param_String = SP_PARAMTYPE_STRING,                     
                Param_Array = SP_PARAMTYPE_ARRAY,                       
                Param_VarArgs = SP_PARAMTYPE_VARARG,            
                Param_CellByRef = SP_PARAMTYPE_CELL|SP_PARAMFLAG_BYREF,         
                Param_FloatByRef = SP_PARAMTYPE_FLOAT|SP_PARAMFLAG_BYREF,       
        };
        
        struct ByrefInfo
        {
                unsigned int cells;
                cell_t *orig_addr;
                int flags;
                int sz_flags;
        };

        struct FwdParamInfo
        {
                cell_t val;
                ByrefInfo byref;
                ParamType pushedas;
        };
        
        class IForwardFilter
        {
        public:
                virtual void Preprocess(IPluginFunction *fun, FwdParamInfo *params)
                {
                }
        };

        class IForward : public ICallable
        {
        public:
                virtual ~IForward()
                {
                }
        public:
                virtual const char *GetForwardName() =0;

                virtual unsigned int GetFunctionCount() =0;

                virtual ExecType GetExecType() =0;

                virtual int Execute(cell_t *result, IForwardFilter *filter=NULL) =0;

                virtual int PushArray(cell_t *inarray, unsigned int cells, int flags=0) =0;
        };

        class IChangeableForward : public IForward
        {
        public:
                virtual bool RemoveFunction(IPluginFunction *func) =0;

                virtual unsigned int RemoveFunctionsOfPlugin(IPlugin *plugin) =0;

                virtual bool AddFunction(IPluginFunction *func) =0;

                virtual bool AddFunction(IPluginContext *ctx, funcid_t index) =0;

                virtual bool RemoveFunction(IPluginContext *ctx, funcid_t index) =0;
        };
        
        class IForwardManager : public SMInterface
        {
        public:
                virtual const char *GetInterfaceName()
                {
                        return SMINTERFACE_FORWARDMANAGER_NAME;
                }
                virtual unsigned int GetInterfaceVersion()
                {
                        return SMINTERFACE_FORWARDMANAGER_VERSION;
                }
                virtual bool IsVersionCompatible(unsigned int version)
                {
                        if (version < 2 || version > GetInterfaceVersion())
                        {
                                return false;
                        }
                        return true;
                }
        public:
                virtual IForward *CreateForward(const char *name, 
                                                                                ExecType et, 
                                                                                unsigned int num_params, 
                                                                                const ParamType *types, 
                                                                                ...) =0;

                virtual IChangeableForward *CreateForwardEx(const char *name, 
                                                                                                        ExecType et, 
                                                                                                        int num_params, 
                                                                                                        const ParamType *types, 
                                                                                                        ...) =0;

                virtual IForward *FindForward(const char *name, IChangeableForward **ifchng) =0;

                virtual void ReleaseForward(IForward *forward) =0;
        };
}

/*
 *  In the AMX Mod X model of forwarding, each forward contained a list of pairs, each pair containing
 * a function ID and an AMX structure.  The forward structure itself did very little but hold parameter types.
 * An execution call worked like this:
 *  - executeForward() took in a function id and a list of parameters
 *  - for each contained plugin:
 *   - the list of parameters was preprocessed and pushed
 *   - the call was made
 *   - the list was freed and copybacks were made
 *  - return
 * 
 *  The advantages to this is that the system is very easy to implement, and it's fast. The disadvantage is 
 * varargs tend to be very unforgiving and inflexible, and thus weird problems arose with casting.  You also 
 * lose flexibility, type checking, and the ability to reasonably use variable arguments lists in the VM.
 *
 *  SourceMod replaces this forward system with a far more advanced, but a bit bulkier one. The idea is that 
 * each plugin has a table of functions, and each function is an ICallable object.  As well as being an ICallable, 
 * each function is an IPluginFunction.  An ICallable simply describes the process of adding parameters to a 
 * function call.  An IPluginFunction describes the process of actually calling a function and performing allocation, 
 * copybacks, and deallocations.
 *
 * A very powerful forward system emerges: a Forward is just a collection of IPluginFunctions.  Thus, the same 
 * API can be easily wrapped around a simple list, and it will look transparent to the user.
 * Advantages:
 * 1) "SP Forwards" from AMX Mod X are simply IPluginFunctions without a collection.
 * 2) Forwards are function based, rather than plugin based, and are thus far more flexible at runtime..
 * 3) [2] Individual functions can be paused and more than one function from the same plugin can be hooked.
 * 4) [2] One hook type that used to map to many SP Forwards can now be centralized as one Forward.
 *    This helps alleviate messes like Fakemeta.
 * 5) Parameter pushing is type-checked and allows for variable arguments.
 *
 *  Note that while #2,3,4 could be added to AMX Mod X, the real binding property is #1, which makes the system
 * object oriented, rather than AMX Mod X, which hides the objects behind static functions.  It is entirely a design
 * issue, rather than a usability one.  The interesting part is when it gets to implementation, which has to cache
 * parameter pushing until execution.  Without this, multiple function calls can be started across one plugin, which
 * will result in heap corruption given SourcePawn's implementation.
 *
 * Observe the new calling process:
 * - Each parameter is pushed into a local cache using the ICallable interface.
 * - For each function in the collection:
 *  - Each parameter is decoded and -pushed into the function.
 *  - The call is made.
 * - Return
 *
 *  Astute readers will note the (minor) problems:
 * 1) More memory is used.  Specifically, rather than N params of memory, you now have N params * M plugins.
 *    This is because, again, parameters are cached both per-function and per-forward.
 * 2) There are slightly more calls going around: one extra call for each parameter, since each push is manual.
 *
 * HISTORICAL NOTES:
 *  There used to be a # about copy backs.  
 *  Note that originally, the Forward implementation was a thin wrapper around IForwards.  It did not cache pushes,
 * and instead immediately fired them to each internal plugin.  This was to allow users to know that pointers would 
 * be immediately resolved.  Unfortunately, this became extremely burdensome on the API and exposed many problems,
 * the major (and breaking) one was that two separate Function objects cannot be in a calling process on the same 
 * plugin at once. (:TODO: perhaps prevent that in the IPlugin object?) This is because heap functions lose their order
 * and become impossible to re-arrange without some global heap tracking mechanism.  It also made iterative copy backs 
 * for arrays/references overwhelmingly complex, since each plugin had to have its memory back-patched for each copy.
 *  Therefore, this was scrapped for cached parameters (current implementation), which is the implementation AMX Mod X 
 * uses.  It is both faster and works better.
 */

#endif //_INCLUDE_SOURCEMOD_FORWARDINTERFACE_H_