--- linuxsampler/trunk/src/scriptvm/ScriptVM.h 2015/03/31 17:56:21 2729 +++ linuxsampler/trunk/src/scriptvm/ScriptVM.h 2017/07/15 16:24:59 3311 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014-2015 Christian Schoenebeck + * Copyright (c) 2014-2017 Christian Schoenebeck * * http://www.linuxsampler.org * @@ -15,7 +15,6 @@ #include "../common/global.h" #include "common.h" -#include "CoreVMFunctions.h" namespace LinuxSampler { @@ -67,6 +66,9 @@ * parser errors, you may pass the VMParserContext object to method * exec() for actually executing the script. * + * It is your responsibility to free the returned VMParserContext + * object once you don't need it anymore. + * * @param s - entire source code of the script to be loaded * @returns parsed representation of the script */ @@ -83,6 +85,33 @@ VMParserContext* loadScript(std::istream* is); /** + * Parses a script's source code (passed as argument @a s to this + * method), splits that input up in its individual tokens (i.e. + * keyword, variable name, event name, etc.) and returns all those + * tokens, for the purpose that the caller can provide syntax syntax + * highlighting for the passed script. + * + * This method is actually not used by the sampler at all, it is rather + * provided for external script editor applications, to provide them a + * convenient backend for parsing scripts and providing syntax + * highlighting. + * + * @returns recognized tokens of passed script's source code + */ + std::vector syntaxHighlighting(const String& s); + + /** + * Same as above's syntaxHighlighting() method, but this one reads the + * script's source code from an input stream object (i.e. stdin or a + * file). + * + * @param is - input stream from which the entire source code of the + * script is to be read and loaded from + * @returns recognized tokens of passed script's source code + */ + std::vector syntaxHighlighting(std::istream* is); + + /** * Dumps the translated tree of the already parsed script, given by * argument @a context, to stdout. This method is for debugging purposes * only. @@ -114,7 +143,7 @@ * This method usually blocks until the entire script event handler * block has been executed completely. It may however also return before * completion if either a) a script runtime error occurred or b) the - * script was suspened by the VM (either because script execution + * script was suspended by the VM (either because script execution * exceeded a certain limit of time or the script called the built-in * wait() function). You must check the return value of this method to * find out which case applies. @@ -144,6 +173,17 @@ VMFunction* functionByName(const String& name) OVERRIDE; /** + * Whether the passed built-in function is disabled and should thus be + * ignored by the parser at the passed parser context (parser state + * where the built-in function call occurs). + * + * @param fn - built-in function to be checked + * @param ctx - parser context at the position where the built-in + * function call is located within the script + */ + bool isFunctionDisabled(VMFunction* fn, VMParserContext* ctx) OVERRIDE; + + /** * Returns all built-in integer script variables. This method returns a * STL map, where the map's key is the variable name and the map's value * is the native pointer to the actual built-in variable. @@ -165,33 +205,94 @@ std::map builtInIntArrayVariables() OVERRIDE; /** - * Returns all built-in constant integer script variables, which can - * only be read, but not be altered by scripts. This method returns a - * STL map, where the map's key is the variable name and the map's value - * is the native pointer to the actual built-in constant variable. + * Returns all built-in constant integer script variables, which are + * constant and their final data is already available at parser time + * and won't change during runtime. Providing your built-in constants + * this way may lead to performance benefits compared to using other + * ways of providing built-in variables, because the script parser + * can perform optimizations when the script is refering to such + * constants. + * + * This type of built-in variable can only be read, but not be altered + * by scripts. This method returns a STL map, where the map's key is + * the variable name and the map's value is the final constant data. * * This method is re-implemented by deriving classes to add more use * case specific built-in constant integers. * - * @b Note: the term "constant" is a bit misleading here, since - * built-in constant integer variables may indeed change, i.e. for - * built-in constant integers which i.e. reflect some kind of status of - * the sampler. So rather see them as "read only" variables, not as - * being actually consistent in time. + * @b Note: In case your built-in variable should be read-only but its + * value is not already available at parser time (i.e. because its + * value may change at runtime), then you should add it to + * builtInIntVariables() instead and use the macro + * DECLARE_VMINT_READONLY() to define the variable for read-only + * access by scripts. */ std::map builtInConstIntVariables() OVERRIDE; + /** + * Returns all built-in dynamic variables. This method returns a STL + * map, where the map's key is the dynamic variable's name and the + * map's value is the pointer to the actual object implementing the + * behavior which is actually generating the content of the dynamic + * variable. + * + * This method is re-implemented by deriving classes to add more use + * case specific built-in dynamic variables. + */ + std::map builtInDynamicVariables() OVERRIDE; + + /** + * Enables or disables automatic suspension of scripts by the VM. + * If automatic suspension is enabled then scripts are monitored + * regarding their execution time and in case they are execution + * for too long, then they are automatically suspended by the VM for + * a certain amount of time in order to avoid any RT instablity + * issues caused by bugs in the script, i.e. endless while() loops + * or very large scripts. + * + * Automatic suspension is enabled by default due to the aimed + * real-time context of this virtual machine. + * + * @param b - true: enable auto suspension [default], + * false: disable auto suspension + */ + void setAutoSuspendEnabled(bool b = true); + + /** + * Returns true in case automatic suspension of scripts by the VM is + * enabled. See setAutoSuspendEnabled() for details. + * + * Automatic suspension is enabled by default due to the aimed + * real-time context of this virtual machine. + */ + bool isAutoSuspendEnabled() const; + + VMEventHandler* currentVMEventHandler(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions) VMParserContext* currentVMParserContext(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions) VMExecContext* currentVMExecContext(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions) protected: + VMEventHandler* m_eventHandler; ParserContext* m_parserContext; - CoreVMFunction_message fnMessage; - CoreVMFunction_exit fnExit; - CoreVMFunction_wait fnWait; - CoreVMFunction_abs fnAbs; - CoreVMFunction_random fnRandom; - CoreVMFunction_num_elements fnNumElements; + bool m_autoSuspend; + class CoreVMFunction_message* m_fnMessage; + class CoreVMFunction_exit* m_fnExit; + class CoreVMFunction_wait* m_fnWait; + class CoreVMFunction_abs* m_fnAbs; + class CoreVMFunction_random* m_fnRandom; + class CoreVMFunction_num_elements* m_fnNumElements; + class CoreVMFunction_inc* m_fnInc; + class CoreVMFunction_dec* m_fnDec; + class CoreVMFunction_in_range* m_fnInRange; + class CoreVMFunction_sh_left* m_fnShLeft; + class CoreVMFunction_sh_right* m_fnShRight; + class CoreVMFunction_min* m_fnMin; + class CoreVMFunction_max* m_fnMax; + class CoreVMFunction_array_equal* m_fnArrayEqual; + class CoreVMFunction_search* m_fnSearch; + class CoreVMFunction_sort* m_fnSort; + class CoreVMDynVar_NKSP_REAL_TIMER* m_varRealTimer; + class CoreVMDynVar_NKSP_PERF_TIMER* m_varPerfTimer; }; } // namespace LinuxSampler