/[svn]/linuxsampler/trunk/src/scriptvm/common.h
ViewVC logotype

Diff of /linuxsampler/trunk/src/scriptvm/common.h

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 2885 by schoenebeck, Fri Apr 22 15:37:45 2016 UTC revision 2960 by schoenebeck, Sun Jul 17 12:10:06 2016 UTC
# Line 160  namespace LinuxSampler { Line 160  namespace LinuxSampler {
160           * @see exprType()           * @see exprType()
161           */           */
162          VMIntArrayExpr* asIntArray() const;          VMIntArrayExpr* asIntArray() const;
163    
164            /**
165             * Returns true in case this expression can be considered to be a
166             * constant expression. A constant expression will retain the same
167             * value throughout the entire life time of a script and the
168             * expression's constant value may be evaluated already at script
169             * parse time, which may result in performance benefits during script
170             * runtime.
171             *
172             * @b NOTE: A constant expression is per se always also non modifyable.
173             * But a non modifyable expression may not necessarily be a constant
174             * expression!
175             *
176             * @see isModifyable()
177             */
178            virtual bool isConstExpr() const = 0;
179    
180            /**
181             * Returns true in case this expression is allowed to be modified.
182             * If this method returns @c false then this expression must be handled
183             * as read-only expression, which means that assigning a new value to it
184             * is either not possible or not allowed.
185             *
186             * @b NOTE: A constant expression is per se always also non modifyable.
187             * But a non modifyable expression may not necessarily be a constant
188             * expression!
189             *
190             * @see isConstExpr()
191             */
192            bool isModifyable() const;
193      };      };
194    
195      /** @brief Virtual machine integer expression      /** @brief Virtual machine integer expression
# Line 366  namespace LinuxSampler { Line 396  namespace LinuxSampler {
396          virtual ExprType_t argType(int iArg) const = 0;          virtual ExprType_t argType(int iArg) const = 0;
397    
398          /**          /**
399           * This function is called by the parser to check whether arguments           * This method is called by the parser to check whether arguments
400           * passed in scripts to this function are accepted by this function. If           * passed in scripts to this function are accepted by this function. If
401           * a script calls this function with an argument's data type not           * a script calls this function with an argument's data type not
402           * accepted by this function, the parser will throw a parser error. On           * accepted by this function, the parser will throw a parser error. On
# Line 384  namespace LinuxSampler { Line 414  namespace LinuxSampler {
414          virtual bool acceptsArgType(int iArg, ExprType_t type) const = 0;          virtual bool acceptsArgType(int iArg, ExprType_t type) const = 0;
415    
416          /**          /**
417             * This method is called by the parser to check whether some arguments
418             * (and if yes which ones) passed to this script function will be
419             * modified by this script function. Most script functions simply use
420             * their arguments as inputs, that is they only read the argument's
421             * values. However some script function may also use passed
422             * argument(s) as output variables. In this case the function
423             * implementation must return @c true for the respective argument
424             * index here.
425             *
426             * @param iArg - index of the function argument in question
427             *               (must be between 0 .. maxAllowedArgs() - 1)
428             */
429            virtual bool modifiesArg(int iArg) const = 0;
430    
431            /**
432           * Implements the actual function execution. This exec() method is           * Implements the actual function execution. This exec() method is
433           * called by the VM whenever this function implementation shall be           * called by the VM whenever this function implementation shall be
434           * executed at script runtime. This method blocks until the function           * executed at script runtime. This method blocks until the function
# Line 423  namespace LinuxSampler { Line 468  namespace LinuxSampler {
468      struct VMRelPtr {      struct VMRelPtr {
469          void** base; ///< Base pointer.          void** base; ///< Base pointer.
470          int offset;  ///< Offset (in bytes) relative to base pointer.          int offset;  ///< Offset (in bytes) relative to base pointer.
471            bool readonly; ///< Whether the pointed data may be modified or just be read.
472      };      };
473    
474      /** @brief Pointer to built-in VM integer variable (of C/C++ type int).      /** @brief Pointer to built-in VM integer variable (of C/C++ type int).
# Line 450  namespace LinuxSampler { Line 496  namespace LinuxSampler {
496          VMIntRelPtr() {          VMIntRelPtr() {
497              base   = NULL;              base   = NULL;
498              offset = 0;              offset = 0;
499                readonly = false;
500          }          }
501          VMIntRelPtr(const VMRelPtr& data) {          VMIntRelPtr(const VMRelPtr& data) {
502              base   = data.base;              base   = data.base;
503              offset = data.offset;              offset = data.offset;
504                readonly = false;
505          }          }
506          virtual int evalInt() { return *(int*)&(*(uint8_t**)base)[offset]; }          virtual int evalInt() { return *(int*)&(*(uint8_t**)base)[offset]; }
507          virtual void assign(int i) { *(int*)&(*(uint8_t**)base)[offset] = i; }          virtual void assign(int i) { *(int*)&(*(uint8_t**)base)[offset] = i; }
# Line 536  namespace LinuxSampler { Line 584  namespace LinuxSampler {
584      #define DECLARE_VMINT(basePtr, T_struct, T_member) ( \      #define DECLARE_VMINT(basePtr, T_struct, T_member) ( \
585          (VMRelPtr) {                                     \          (VMRelPtr) {                                     \
586              (void**) &basePtr,                           \              (void**) &basePtr,                           \
587              offsetof(T_struct, T_member)                 \              offsetof(T_struct, T_member),                \
588                false                                        \
589          }                                                \          }                                                \
590      )                                                    \      )                                                    \
591    
592        /**
593         * Same as DECLARE_VMINT(), but this one defines the VMIntRelPtr and
594         * VMInt8RelPtr structures to be of read-only type. That means the script
595         * parser will abort any script at parser time if the script is trying to
596         * modify such a read-only built-in variable.
597         *
598         * @b NOTE: this is only intended for built-in read-only variables that
599         * may change during runtime! If your built-in variable's data is rather
600         * already available at parser time and won't change during runtime, then
601         * you should rather register a built-in constant in your VM class instead!
602         *
603         * @see ScriptVM::builtInConstIntVariables()
604         */
605        #define DECLARE_VMINT_READONLY(basePtr, T_struct, T_member) ( \
606            (VMRelPtr) {                                          \
607                (void**) &basePtr,                                \
608                offsetof(T_struct, T_member),                     \
609                true                                              \
610            }                                                     \
611        )                                                         \
612    
613      /** @brief Built-in VM 8 bit integer array variable.      /** @brief Built-in VM 8 bit integer array variable.
614       *       *
615       * Used for defining built-in integer array script variables (8 bit per       * Used for defining built-in integer array script variables (8 bit per
# Line 553  namespace LinuxSampler { Line 623  namespace LinuxSampler {
623          VMInt8Array() : data(NULL), size(0) {}          VMInt8Array() : data(NULL), size(0) {}
624      };      };
625    
626        /** @brief Virtual machine script variable.
627         *
628         * Common interface for all variables accessed in scripts.
629         */
630        class VMVariable : virtual public VMExpr {
631        public:
632            /**
633             * Whether a script may modify the content of this variable by
634             * assigning a new value to it.
635             *
636             * @see isConstExpr(), assign()
637             */
638            virtual bool isAssignable() const = 0;
639    
640            /**
641             * In case this variable is assignable, this method will be called to
642             * perform the value assignment to this variable with @a expr
643             * reflecting the new value to be assigned.
644             *
645             * @param expr - new value to be assigned to this variable
646             */
647            virtual void assignExpr(VMExpr* expr) = 0;
648        };
649        
650        /** @brief Dynamically executed variable (abstract base class).
651         *
652         * Interface for the implementation of a dynamically generated content of
653         * a built-in script variable. Most built-in variables are simply pointers
654         * to some native location in memory. So when a script reads them, the
655         * memory location is simply read to get the value of the variable. A
656         * dynamic variable however is not simply a memory location. For each access
657         * to a dynamic variable some native code is executed to actually generate
658         * and provide the content (value) of this type of variable.
659         */
660        class VMDynVar : public VMVariable {
661        public:
662            /**
663             * Returns true in case this dynamic variable can be considered to be a
664             * constant expression. A constant expression will retain the same value
665             * throughout the entire life time of a script and the expression's
666             * constant value may be evaluated already at script parse time, which
667             * may result in performance benefits during script runtime.
668             *
669             * However due to the "dynamic" behavior of dynamic variables, almost
670             * all dynamic variables are probably not constant expressions. That's
671             * why this method returns @c false by default. If you are really sure
672             * that your dynamic variable implementation can be considered a
673             * constant expression then you may override this method and return
674             * @c true instead. Note that when you return @c true here, your
675             * dynamic variable will really just be executed once; and exectly
676             * already when the script is loaded!
677             *
678             * As an example you may implement a "constant" built-in dynamic
679             * variable that checks for a certain operating system feature and
680             * returns the result of that OS feature check as content (value) of
681             * this dynamic variable. Since the respective OS feature might become
682             * available/unavailable after OS updates, software migration, etc. the
683             * OS feature check should at least be performed once each time the
684             * application is launched. And since the OS feature check might take a
685             * certain amount of execution time, it might make sense to only
686             * perform the check if the respective variable name is actually
687             * referenced at all in the script to be loaded. Note that the dynamic
688             * variable will still be evaluated again though if the script is
689             * loaded again. So it is up to you to probably cache the result in the
690             * implementation of your dynamic variable.
691             *
692             * On doubt, please rather consider to use a constant built-in script
693             * variable instead of implementing a "constant" dynamic variable, due
694             * to the runtime overhead a dynamic variable may cause.
695             *
696             * @see isAssignable()
697             */
698            bool isConstExpr() const OVERRIDE { return false; }
699    
700            /**
701             * In case this dynamic variable is assignable, the new value (content)
702             * to be assigned to this dynamic variable.
703             *
704             * By default this method does nothing. Override and implement this
705             * method in your subclass in case your dynamic variable allows to
706             * assign a new value by script.
707             *
708             * @param expr - new value to be assigned to this variable
709             */
710            void assignExpr(VMExpr* expr) OVERRIDE {}
711        };
712    
713        /** @brief Dynamically executed variable (of integer data type).
714         *
715         * This is the base class for all built-in integer script variables whose
716         * variable content needs to be provided dynamically by executable native
717         * code on each script variable access.
718         */
719        class VMDynIntVar : virtual public VMDynVar, virtual public VMIntExpr {
720        public:
721        };
722    
723        /** @brief Dynamically executed variable (of string data type).
724         *
725         * This is the base class for all built-in string script variables whose
726         * variable content needs to be provided dynamically by executable native
727         * code on each script variable access.
728         */
729        class VMDynStringVar : virtual public VMDynVar, virtual public VMStringExpr {
730        public:
731        };
732    
733      /** @brief Provider for built-in script functions and variables.      /** @brief Provider for built-in script functions and variables.
734       *       *
735       * Abstract base class defining the high-level interface for all classes       * Abstract base class defining the high-level interface for all classes
# Line 587  namespace LinuxSampler { Line 764  namespace LinuxSampler {
764           * variables, which never change their value at runtime.           * variables, which never change their value at runtime.
765           */           */
766          virtual std::map<String,int> builtInConstIntVariables() = 0;          virtual std::map<String,int> builtInConstIntVariables() = 0;
767    
768            /**
769             * Returns a variable name indexed map of all built-in dynamic variables,
770             * which are not simply data stores, rather each one of them executes
771             * natively to provide or alter the respective script variable data.
772             */
773            virtual std::map<String,VMDynVar*> builtInDynamicVariables() = 0;
774      };      };
775    
776      /** @brief Execution state of a virtual machine.      /** @brief Execution state of a virtual machine.
# Line 667  namespace LinuxSampler { Line 851  namespace LinuxSampler {
851       */       */
852      struct ParserIssue {      struct ParserIssue {
853          String txt; ///< Human readable explanation text of the parser issue.          String txt; ///< Human readable explanation text of the parser issue.
854          int line; ///< Line number within the script where this issue was encountered.          int firstLine; ///< The first line number within the script where this issue was encountered (indexed with 1 being the very first line).
855            int lastLine; ///< The last line number within the script where this issue was encountered.
856            int firstColumn; ///< The first column within the script where this issue was encountered (indexed with 1 being the very first column).
857            int lastColumn; ///< The last column within the script where this issue was encountered.
858          ParserIssueType_t type; ///< Whether this issue is either a parser error or just a parser warning.          ParserIssueType_t type; ///< Whether this issue is either a parser error or just a parser warning.
859    
860          /**          /**
# Line 676  namespace LinuxSampler { Line 863  namespace LinuxSampler {
863          inline void dump() {          inline void dump() {
864              switch (type) {              switch (type) {
865                  case PARSER_ERROR:                  case PARSER_ERROR:
866                      printf("[ERROR] line %d: %s\n", line, txt.c_str());                      printf("[ERROR] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str());
867                      break;                      break;
868                  case PARSER_WARNING:                  case PARSER_WARNING:
869                      printf("[Warning] line %d: %s\n", line, txt.c_str());                      printf("[Warning] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str());
870                      break;                      break;
871              }              }
872          }          }
# Line 791  namespace LinuxSampler { Line 978  namespace LinuxSampler {
978          String text() const;          String text() const;
979    
980          // position of token in script          // position of token in script
981          int firstLine() const;          int firstLine() const; ///< First line this source token is located at in script source code (indexed with 0 being the very first line).
982          int firstColumn() const;          int firstColumn() const; ///< Last line this source token is located at in script source code.
983    
984          // base types          // base types
985          bool isEOF() const;          bool isEOF() const;
Legend:
Removed from v.2885  
changed lines
  Added in v.2960
  ViewVC Help
Powered by ViewVC