root/inc/cilVm.h

/****************************************************************************
 *
 * CRI Middleware SDK
 *
 * Copyright (c) 2008 CRI Middleware, Inc. All rights reserved.
 *
 * Use, modification and distribution are subject to the CRI Script Software
 * License, Version 1.0(see accompanying file "CriScript_License_1_0.txt" or
 * copy at www.criscript.com/trac/wiki/CRI%20Script%20Software%20License%201.0 ).
 *
 *
 * Library  : CRIScript
 * Module   : cil VM definitions
 * File     : cilVm.h
 * Date     : 
 * Version  : 
 *
 ****************************************************************************/
#pragma once

#include "criscript.h"
#include "versions.h"
#include "iCodeGen.h"
#include "cilCodeGen.h"
#include "variable.h"
#include "vmRuntimeError.h"

using namespace std;

namespace cri {

/***************************************************************************
 *      VM costants
 ***************************************************************************/
const int32_t LONGBR_ADJUST = 4;
const int32_t SHORTBR_ADJUST = 1;
const int32_t SIZE_LONGBR = 5;
const int32_t SIZE_SHORTBR = 2;

class CVmObject;

typedef CVmObject* VMOBJECTREF;

const int32_t VM_REFCOUNT_MANAGED = 0;//0x40000000;

/*EN Maximum callstack entries in a VM. assertion is triggerred when the callstack entries exceeds this number.
Note: Need tail recursion optimization
\ingroup MDL_LIB_VM
*/
const int32_t MAX_CALLSTACK = 512;

/*EN Maximum evalstack entries in a VM. assertion is triggerred when the evalstack entries exceeds this number.
Note: Future optimization: Now eval stack push/pop involves ref count inc/dec. Needs non ref counter implementation.
\ingroup MDL_LIB_VM
*/
const int32_t MAX_EVALSTACK = 4096;

/*EN Maximum local variable stack entries in a VM. assertion is triggerred when the local variable stack entries exceeds this number.
\ingroup MDL_LIB_VM
*/
const int32_t MAX_LOCAL_VARIABLE = 256;

/*EN Maximum argument variable stack entries in a VM. assertion is triggerred when the argument variable stack entries exceeds this number.
\ingroup MDL_LIB_VM
*/
const int32_t MAX_ARG_VARIABLE = 1024;


/***************************************************************************
 *      VM HANDLER Type
 ***************************************************************************/
/*EN User speficied VM handler types
\ingroup MDL_LIB_VM
*/
enum VM_HANDLER_TYPE {
        VM_HANDLER_EXCEPTIONNOTHANDLED, /*EN< Callback invoked when the exception is not handled*/
        VM_HANDLER_MAX,
};

/*EN VM callback function signature
\ingroup MDL_LIB_VM
*/
typedef void( *VM_HANDLER_CALLBACK )( int32_t iType, CVariable* pVar );


/***************************************************************************
 *      VM status enum
 ***************************************************************************/
/*EN Current VM statuses
\ingroup MDL_LIB_VM
*/
enum VM_STATUS_TYPE {
        VM_EXECUTE_INITIALIZING,        /*EN< VM instance is created but still not initialized yet*/
        VM_EXECUTE_INITIALIZED,         /*EN< VM instance is initialized but still not executed yet*/
        VM_EXECUTE_EXECUTING,           /*EN< VM instance is initialized but still not executed yet*/
        VM_EXECUTE_DONE,                        /*EN< Byte code execution is finished successfully*/
        VM_EXECUTE_SUSPENDED,           /*EN< VM suspended by resume() call. Not implemented yet*/
        VM_EXECUTE_SWAPPEDOUT,          /*EN< VM time slice is ended and current context is swapped out. not implemented yet.*/
        VM_EXECUTE_ERROR,                       /*EN< VM is in the error state*/
};

/***************************************************************************
 *      VM reset Type
 ***************************************************************************/
/*EN VM reset type
\ingroup MDL_LIB_VM
*/
enum VM_RESET_TYPE {
        VM_RESET_DEFAULT,       /*EN< Reset VM to the initialized status
                                                                All the fields values, objects statuses are reset.*/
};


/***************************************************************************
 *      Callstack slot info
 ***************************************************************************/
/*EN Callstack type
\ingroup MDL_LIB_VM
*/
enum VM_CALLSTACK_TYPE {
        VM_CALLSTACK_CALLSTACK, /*EN< Regular call stack */
        VM_CALLSTACK_EH,                /*EN< Excepiton handling clause */
};

/*EN Execution status of the current clause
\ingroup MDL_LIB_VM
*/
enum VM_EHCLAUSESTATUS_TYPE {
        VM_EHCLAUSE_NORMAL                              =  0,           /*EN< Executing normally */
        VM_EHCLAUSE_EXECUTING_CATCH             = -1,           /*EN< Executing catch clause */
        VM_EHCLAUSE_EXECUTING_FINALLY   = -2,           /*EN< Executing finally clause */
        VM_EHCLAUSE_RETURNING                   = -3,           /*EN< Returning from EH clause */
        VM_EHCLAUSE_EXECUTED_CATCH              = -4,           /*EN< Executed catch clause */
};

/*EN Structure that represent a call stack information
\ingroup MDL_LIB_VM
*/
struct VM_CALLSTACK {
        VM_CALLSTACK_TYPE               type;                                   /*EN< Type of call stack*/
        RID                                             ridMethod;                              /*EN< Method RID*/
        uint8_t*                                pInstruction;                   /*EN< Return Instruction pointer*/
        VM_EHCLAUSESTATUS_TYPE  status;                                 /*EN< Current execution status*/
        union {
                /*EN Local variable start index*/
                int32_t                 iLocalVariableStartIndex;       
                /*EN Catch clause RID*/
                RID                                     ridCatch;
        };
        union {
                /*EN Argument list start index*/
                int32_t                 iArgumentListStartIndex;
                /*EN Finally clause RID*/
                RID                                     ridFinally;
        };
        /*EN Number of an argument used in the method*/
        uint8_t                         iNumArgument;
        /*EN Number of an argument given by callee*/
        uint8_t                         iNumGivenArgument;
        /*EN Flag that indicates if it's calling ctor.
        When calling ctor, return value needed to be avoided*/
        bool                            bConstructor;
};

/***************************************************************************
 *      VM object definition
 ***************************************************************************/
/*EN
 A pointer to the CVmObject. Inherit a Code generation object metadata
 \ingroup MDL_LIB_VM
*/
class CVmObject : public CObjectTypeInfo {
        int32_t         m_iRefCount;    /*EN< Reference Counter*/
        CVariable       m_varPrototype; /*EN< A prototype object value*/
        CVariable       m_varParent;    /*EN< A parent value, needed for a property access*/
        CVariable       m_varValue;             /*EN< A value of the object*/

        /*EN An accessor for the prototype varialbe*/
        static CVariable* prototypeAccessor(CCilVm* const pVm,
                                                                                CVmObject* const pObject, 
                                                                                const wstring* const pName,
                                                                                CVariable* const var,
                                                                                const bool bSet );

public:
        CVmObject();                                                    /*EN< ctor*/
        ~CVmObject();                                                   /*EN< dtor*/
        CVmObject( const CVmObject& right );    /*EN< Copy ctor*/

        /*EN Increments a reference count of the object.
        \return current reference count value
        */
        int32_t addRef();

        /*EN Decrements a reference count of the object.
        \return current reference count value
        */
        int32_t release();

        /*EN Enforce to set a reference count of the object.
        \param iCount new reference count value to be set
        */
        void setRefCount( int32_t iCount ) { m_iRefCount = iCount; }

        /*EN Retrieves a reference count of the object.
        \return areference count value
        */
        int32_t getRefCount() { return m_iRefCount; }

        /*EN Clears a reference count value to 0.
        */
        void clearRefCount( void );
        /*EN Sets a prototype object.
        \param pPrototype A pointer to the prototype VM Object
        \param type operand type, usually OPERAND_OBJECTREF.
        \param flag flags
        */
        void setPrototypeObject( CVmObject* const pPrototype,
                                                                const OPERAND_TYPE type = OPERAND_OBJECTREF,
                                                                const OPERAND_FLAG flag = OPERAND_FLAG( OPERAND_FLAG_DONTDELETE
                                                                                                        | OPERAND_FLAG_DONTENUM ) )
        {
                assert( type == OPERAND_OBJECTREF );
                m_varPrototype.setObjectRefWithFlags( pPrototype, flag, RID_NULL );
        }

        /*EN Retrieves a prototype object.
        \return A prototype object reference.
        A prototype object has a chain and finally goes to the Object prototype object.
        */
        CVmObject* getPrototypeObject( void ) { return m_varPrototype.refObject; }

        /*EN Looks up the property with the given name
        Use this version only when you are sure getter/setters are not involved in.
        \param str A name of the property
        \return A pointers to a value of the property. Returns NULL if a requested property does not exist.
        */
        CVariable* lookupProperty( const wstring& str );

        /*EN Retrieves an iterator tothe property with the given name
        Use this version only when you are sure getter/setters are not involved in.
        \param str A name of the property
        \return An iterator of the property. Returns invalid iterator when the property does not exist.
        */
        hash_map< wstring, CVariable >::iterator lookupPropertyIterator( const wstring& str );

        /*EN Sets the property value with the given name
        Use this version only when you are sure getter/setters are not involved in.
        \param str A name of the property
        \param value value of the property
        */
        void setProperty( const wstring& str, CVariable& value );

        /*EN Looks up the property with the given name.
        This version can invoke a getter.
        \param pVm A pointer to the VM instance
        \param str A name of the property
        \return A pointers to a value of the property. Returns NULL if a requested property does not exist.
        */
        CVariable* lookupProperty( CCilVm* const pVm, const wstring& str, CVariable* const pThis = NULL );

        /*EN Sets the property value with the given name
        This version can invoke a setter.
        Use this version only when you are sure getter/setters are not involved in.
        \param pVm A pointer to the VM instance
        \param str A name of the property
        \param value value of the property
        */
        void setProperty( CCilVm* const pVm, const wstring& str, CVariable& value );

        /*EN Sets the method property with the given name
        \param pVm A pointer to the VM instance
        \param name A name of the property
        \param ridMethod RID value of the method
        \param iLength A number of parameters that the method can accept. This value is set to method.length property.
        */
        void setProperty( CCilVm* const pVm,
                                 const wstring& name,
                                 const RID ridMethod,
                                 const int32_t iLength );

        /*EN Removes a specified property.
        \param name A name of the property to be removed
        */
        void removeProperty( const wstring& name );

        /*EN Sets a property accessor.
        \param name A name of the property that the accessor will be set
        \param pAccessro A pointer of the accessor callback
        */
        void setPropertyAccessor( const wstring& name, PACCESSORMETHOD pAccessor );

        /*EN Retrieves a value of the object.
        \return value of the object
        */
        CVariable& getValue( void )
        {
                return m_varValue;
        }

        /*EN Set a value of the object.
        \param var an object value
        */
        void setValue( CVariable& var )
        {
                var.moveTo( m_varValue );
                return;
        }

        /*EN Retrieves a parent variable of the object.
        \return value of the object
        */
        CVariable& getParentVariable( void ) { return m_varParent; }

        /*EN Set a parent value of the object.
        \param variable a parent value of the object value
        */
        void setParentVariable( const CVariable& variable ) { m_varParent = variable; }

};

//Some forward decl
class CCilDebugger;

/***************************************************************************
 *      CIL VM implementation
 ***************************************************************************/
        /*EN
         \brief The VM class for CRI Script byte code strem
         \ingroup MDL_LIB_VM
        */
        class CCilVm
        {
        public:
                CCilVm();       /*EN< ctor*/
                ~CCilVm();      /*EN< dtor*/

                /*EN Initialize the VM.
                \return true when the initialization succeeded.
                */
                bool init();

                /*EN verify an attathed byte code stream.
                \return true when the verification succeeded.
                */
                bool verify();

                /*EN reset VM status to Initilized status
                \param iResetType VM reset type
                \return true when the reset succeeded.
                */
                bool reset( const VM_RESET_TYPE iResetType );

                /*EN Retrieve Version Number of the VM */
                const CRISCRIPT_VERSIONS& getVersions(void) { return criscript_version_struct; }

                //----------------------------------------------------------------------
                //VM Management
                //----------------------------------------------------------------------
                /*EN execute the byte code.
                \return current execution status.
                */
                VM_STATUS_TYPE execute();

                /*EN Retrieves an exit code of the script.
                \return exit code value. If the exit code can not be converted via ToNumber(), 0 is returned.
                An exit code is set from the script variable 'System.Environment.ExitCode' .
                */
                int32_t getExitCode();

                //----------------------------------------------------------------------
                //Register Handler
                //----------------------------------------------------------------------
                /*EN Register VM handlers.
                \return a handler which was set prior to the given handler. New handler should make sure to call prior set handler.
                \param handlertype handler type to set
                \param pCallBack a callback pointer
                */
                VM_HANDLER_CALLBACK registerHandler( VM_HANDLER_TYPE handlertype, VM_HANDLER_CALLBACK pCallBack );

                //----------------------------------------------------------------------
                //Initialize engines
                //----------------------------------------------------------------------
                /*EN Attaches an IL(intermediate language) stream to the VM.
                return: true when succeeded.
                */
                bool setILPool( const std::vector< uint8_t >& vecIL);
                
                /*EN Attaches an IL(intermediate language) stream to the VM.
                 return: true when succeeded.
                 */
                bool setILPool( const uint8_t* pILPool, const size_t size_t);

                /*EN Attaches a metadata for corresponding IL(intermediate language) stream to the VM.
                \return true when succeeded.
                */
                bool setMetaData( CMetaData& MetaData );

                /*EN Retrieves currently set metadata.
                \return currently set metadata.
                */
                CMetaData& getMetaData() { return m_MetaData; }

                /*EN Binds a built in method to the VM.
                \param strQualifiedName Fully qualified name of the method that need to be bound.
                \param pMethod A pointer to the method that need to be bound.
                \param iLength A number of arguments that the method can accept. This number is set to method.length property.
                \return true when the binding succeeded, false otherwise.
                */
                bool bindBuiltinMethod( const wstring& strQualifiedName,
                                                                PMETHOD const pMethod,
                                                                const int32_t iLength );

                /*EN Binds a built in method to the VM with a wrapper code given.
                \param strQualifiedName Fully qualified name of the method that need to be bound.
                \param pMethod A pointer to the wrapper code that is generated semi-automatically.
                \param pMethodBody A pointer to the method that need to be bound.
                \return true when the binding succeeded, false otherwise.
                */
                bool bindBuiltinMethod( const wstring& strQualifiedName,
                                                                PMETHOD const pMethod, PMETHOD const pMethodBody );

                /*EN Binds a built in method to the VM.
                \param strQualifiedName Fully qualified name of the variable that need to be bound.
                \param pvar A pointer to the variable that need to be bound.
                \return true when the binding succeeded, false otherwise.
                */
                bool bindBuiltinVariable( const wstring& strQualifiedName,
                                                                CVariable* const pvar );

                //----------------------------------------------------------------------
                //Field accesssor
                //----------------------------------------------------------------------
                /*EN Retrieve a static field value with given RID.
                \param rid RID to retrieve a value.
                \return variable that with given RID
                */
                CVariable& getStaticField( const RID rid );

                /*EN Set a static field value with given RID.
                \param rid RID to set a value.
                \param value a reference to a value to set.
                \return true when the value is set successfully, false otherwise.
                */
                bool setStaticField( const RID rid, const CVariable& value );

                /*EN Set a static field value with given RID.
                \param rid RID of the static field to be initialized
                \param value a reference to a value to set.
                \param bForce true enforces an overwriting the value even READONLY flag is set.
                \return true when the value is set successfully, false otherwise.
                */
                bool setStaticField( const RID rid, const CVariable& value, bool bForce );
                
                //----------------------------------------------------------------------
                //Debug functions
                //----------------------------------------------------------------------
                /*EN Attaches a debugger interface to the VM.
                \param pDebugger A pointer to the debugger interface
                \return true when the debugger successfully attached. false otherwise.
                */
                bool attachDebugger( CCilDebugger* const pDebugger ) { m_pDebugger = pDebugger; return true; }
                
                /*EN Dettaches a debugger interface from the VM.
                \return true when the debugger successfully dettached. false otherwise.
                */
                bool detachDebugger() { m_pDebugger = NULL; return true; }
                
                /*EN Sets a map of symbol information.
                \attention Symbol information and metadata APIs will be redesigned later.
                \param symbolinfo map of the symbol information.
                \return true when the symbol information map successfully set. false otherwise.
                */
                bool setSymbolInformation( hash_map<wstring, CG_SYMBOL_INFORMATION>& symbolinfo);

                /*EN Query a symbol information
                \param symbolName Fully qualified name of the symbol.
                \return Information related to hte symbol
                */
                CG_SYMBOL_INFORMATION& querySymbolInformation( const wstring& symbolName );

                /*EN dump current VM status including variables and IL stream to stdout. This API is for Debug purpose.
                */
                void debugDumpStats( void );

                //----------------------------------------------------------------------
                //Invoke method from outside of the current context
                //----------------------------------------------------------------------
                /*EN Invokes a methods directly from C++ code.
                \return A return value from the byte code method.
                        Returned value need to be freed as a caller's responsibility.
                \param ridMethod RID of the calling method.
                \param iNumArg A number of arguments for the methods.
                \param pArguments A pointer to the argument array
                */
                CVariable* invokeMethod( const RID ridMethod, const int32_t iNumArg,
                                                                                           CVariable* pArguments );

                //----------------------------------------------------------------------
                //Get object pool
                //----------------------------------------------------------------------
                /*EN Retrieves an object pool list
                \return A reference to the object pool. An object pool is a implemented with STL::list
                */
                list< CVmObject >& getObjectPool() { return m_ObjectPool; }

                /*EN Retrieves a prototype object for given RID
                \return A reference to the prototype object.
                */
                CVmObject& getPrototypeObject( const RID ridPrototype );

                //----------------------------------------------------------------------
                //Throw an exception from the API
                //----------------------------------------------------------------------
                /*EN Throws an exception from inside of built-in functions.
                \param errObject a pointer to the error object.
                */
                void throwException( CVariable* errObject );
                /*EN Throws an exception from inside of built-in functions.
                \param pstrMessage A pointer to an error description
                \param pstrName A pointer to an error name
                \param iNumber A pointer to an error number
                */
                void throwException( wstring* pstrMessage, wstring* pstrName = NULL , int32_t iNumber = -1 );

                //----------------------------------------------------------------------
                //Object handlings
                //----------------------------------------------------------------------
                /*EN Creates a prototype objecft with given RIDs
                \param ridObject RID of the prototype object
                \param ridObjectName String RID of the object name
                \param ridPrototype Object RID of a prototype object for the object
                \return RID of created prototype object
                */
                RID createPrototypeObject( const RID ridObject,
                                                                const RID ridObjectName,
                                                                const RID ridPrototype );

                /*EN Creates an object with given RID and store it to the object pool
                \param ridObject RID of the object to be created
                \return A pointer to the created object. An object resides in a object pool and has reference count for Garbage collector,
                */
                VMOBJECTREF createObject( const RID ridObject );

                /*EN Retrieve an object from the variable. If the variable is not an object, a prototype object reference is returned.
                \param var A reference to the variable
                \return A pointer to the object or prototype object that corresponds to the variable type
                */
                VMOBJECTREF getObjectPointer( CVariable& var );

                //----------------------------------------------------------------------
                //Static members
                //----------------------------------------------------------------------
                /*EN Retrieves Object prototype object RID
                \return RID of the Object prototype object
                */
                static RID getObjectRID() { return m_ridObject; }
                /*EN Retrieves Array prototype object RID
                \return RID of the Array prototype object
                */
                static RID getArrayObjectRID() { return m_ridArrayObject; }
                /*EN Retrieves String prototype object RID
                \return RID of the String prototype object
                */
                static RID getStringObjectRID() { return m_ridStringObject; }
                /*EN Retrieves Function prototype object RID
                \return RID of the Function prototype object
                */
                static RID getFunctionObjectRID() { return m_ridFunctionObject; }
                /*EN Retrieves System prototype object RID
                \return RID of the System prototype object
                */
                static RID getSystemObjectRID() { return m_ridSystemObject; }
                /*EN Retrieves Boolean prototype object RID
                \return RID of the Boolean prototype object
                */
                static RID getBooleanObjectRID() { return m_ridBooleanObject; }
                /*EN Retrieves Number prototype object RID
                \return RID of the Number prototype object
                */
                static RID getNumberObjectRID() { return m_ridNumberObject; }
                /*EN Retrieves Date prototype object RID
                \return RID of the Date prototype object
                */
                static RID getDateObjectRID() { return m_ridDateObject; }
                /*EN Retrieves Regex prototype object RID
                \return RID of the Regex prototype object
                */
                static RID getRegexObjectRID() { return m_ridRegexObject; }
                /*EN Retrieves Error prototype object RID
                \return RID of the Error prototype object
                */
                static RID getErrorObjectRID() { return m_ridErrorObject; }
                /*EN Retrieves Math prototype object RID
               &n