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

Annotation of /linuxsampler/trunk/src/scriptvm/ScriptVM.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3551 - (hide annotations) (download) (as text)
Thu Aug 1 10:22:56 2019 UTC (4 years, 8 months ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 14985 byte(s)
* Added test cases for NKSP core language aspects and core built-in
  functions.
* NKSP: Added method ScriptVM::setExitResultEnabled() which allows
  to explicitly enable the built-in exit() function to optionally
  accept one function argument; the value of the passed exit()
  function argument will then become available by calling
  VMExecContext::exitResult() after script execution.
* Bumped version (2.1.1.svn2).

1 schoenebeck 2581 /*
2 schoenebeck 3551 * Copyright (c) 2014-2019 Christian Schoenebeck
3 schoenebeck 2581 *
4     * http://www.linuxsampler.org
5     *
6     * This file is part of LinuxSampler and released under the same terms.
7     * See README file for details.
8     */
9    
10     #ifndef LS_SCRIPTVM_H
11     #define LS_SCRIPTVM_H
12    
13     #include <iostream>
14     #include <vector>
15    
16     #include "../common/global.h"
17     #include "common.h"
18    
19     namespace LinuxSampler {
20    
21     class ParserContext;
22 schoenebeck 2588 class ExecContext;
23 schoenebeck 2581
24 schoenebeck 2594 /** @brief Core virtual machine for real-time instrument scripts.
25     *
26 schoenebeck 2727 * This is the core of the virtual machine and main entry class, used for
27     * running real-time instrument scripts. This VM core encompasses the
28     * instrument script parser, generalized virtual machine and very generic
29     * built-in script functions. Thus this class only provides functionalities
30     * which are yet independent of the actual purpose the virtual machine is
31     * going to be used for.
32 schoenebeck 2594 *
33     * The actual use case specific functionalites (i.e. MIDI processing) is
34 schoenebeck 2727 * then implemented by sampler engines' VM classes which are derived from
35     * this generalized ScriptVM class.
36 schoenebeck 2594 *
37 schoenebeck 2727 * Typical usage of this class:
38     *
39     * - 1. Create an instance of this ScriptVM class (or of one of its deriving
40     * classes).
41     * - 2. Load a script by passing its source code to method loadScript(),
42 schoenebeck 2729 * which will return the parsed representation of the script.
43 schoenebeck 2727 * - 3. Create a VM execution context by calling createExecContext().
44     * - 4. Execute the script by calling method exec().
45     *
46 schoenebeck 2594 * This class is re-entrant safe, but not thread safe. So you can share one
47     * instance of this class between multiple (native) threads, but you @b must
48     * @b not execute methods of the same class instance simultaniously from
49     * different (native) threads. If you want to execute scripts simultaniously
50     * multi threaded, then create a separate ScriptVM instance for each
51     * (native) thread. Also note that one VMParserContext instance is tied to
52     * exactly one ScriptVM instance. So you @b must @b not create a
53     * VMParserContext with one ScriptVM instance and run it with a different
54     * ScriptVM instance!
55     */
56 schoenebeck 2581 class ScriptVM : public VMFunctionProvider {
57     public:
58     ScriptVM();
59     virtual ~ScriptVM();
60 schoenebeck 2727
61     /**
62     * Loads a script given by its source code (passed as argument @a s to
63 schoenebeck 2729 * this method) and returns the parsed representation of that script.
64 schoenebeck 2727 * After calling this method you must check the returned VMParserContext
65     * object whether there had been any parser errors. If there were no
66     * parser errors, you may pass the VMParserContext object to method
67     * exec() for actually executing the script.
68     *
69 schoenebeck 2889 * It is your responsibility to free the returned VMParserContext
70     * object once you don't need it anymore.
71     *
72 schoenebeck 2727 * @param s - entire source code of the script to be loaded
73 schoenebeck 2729 * @returns parsed representation of the script
74 schoenebeck 2727 */
75 schoenebeck 2588 VMParserContext* loadScript(const String& s);
76 schoenebeck 2727
77     /**
78     * Same as above's loadScript() method, but this one reads the script's
79     * source code from an input stream object (i.e. stdin or a file).
80     *
81     * @param is - input stream from which the entire source code of the
82     * script is to be read and loaded from
83 schoenebeck 2729 * @returns parsed representation of the script
84 schoenebeck 2727 */
85 schoenebeck 2588 VMParserContext* loadScript(std::istream* is);
86 schoenebeck 2727
87     /**
88 schoenebeck 2885 * Parses a script's source code (passed as argument @a s to this
89     * method), splits that input up in its individual tokens (i.e.
90     * keyword, variable name, event name, etc.) and returns all those
91     * tokens, for the purpose that the caller can provide syntax syntax
92     * highlighting for the passed script.
93     *
94     * This method is actually not used by the sampler at all, it is rather
95     * provided for external script editor applications, to provide them a
96     * convenient backend for parsing scripts and providing syntax
97     * highlighting.
98     *
99     * @returns recognized tokens of passed script's source code
100     */
101     std::vector<VMSourceToken> syntaxHighlighting(const String& s);
102    
103     /**
104     * Same as above's syntaxHighlighting() method, but this one reads the
105     * script's source code from an input stream object (i.e. stdin or a
106     * file).
107     *
108     * @param is - input stream from which the entire source code of the
109     * script is to be read and loaded from
110     * @returns recognized tokens of passed script's source code
111     */
112     std::vector<VMSourceToken> syntaxHighlighting(std::istream* is);
113    
114     /**
115 schoenebeck 2727 * Dumps the translated tree of the already parsed script, given by
116     * argument @a context, to stdout. This method is for debugging purposes
117     * only.
118     *
119 schoenebeck 2729 * @param context - parsed representation of the script
120 schoenebeck 2728 * @see loadScript()
121 schoenebeck 2727 */
122 schoenebeck 2588 void dumpParsedScript(VMParserContext* context);
123 schoenebeck 2727
124     /**
125     * Creates a so called VM exceution context for a specific, already
126     * parsed script (provided by argument @a parserContext). Due to the
127     * general real-time design of this virtual machine, the VM execution
128     * context differs for every script. So you must (re)create the
129     * execution context for each script being loaded.
130 schoenebeck 2728 *
131 schoenebeck 2729 * @param parserContext - parsed representation of the script
132 schoenebeck 2728 * @see loadScript()
133 schoenebeck 2727 */
134 schoenebeck 2588 VMExecContext* createExecContext(VMParserContext* parserContext);
135 schoenebeck 2727
136     /**
137     * Execute a script by virtual machine. Since scripts are event-driven,
138     * you actually execute only one specific event handler block (i.e. a
139     * "on note ... end on" code block) by calling this method (not the
140     * entire script), and hence you must provide one precise handler of the
141     * script to be executed by this method.
142     *
143     * This method usually blocks until the entire script event handler
144     * block has been executed completely. It may however also return before
145     * completion if either a) a script runtime error occurred or b) the
146 schoenebeck 2871 * script was suspended by the VM (either because script execution
147 schoenebeck 2727 * exceeded a certain limit of time or the script called the built-in
148     * wait() function). You must check the return value of this method to
149     * find out which case applies.
150     *
151 schoenebeck 2729 * @param parserContext - parsed representation of the script (see loadScript())
152 schoenebeck 2727 * @param execContext - VM execution context (see createExecContext())
153     * @param handler - precise event handler (i.e. "on note ... end on"
154     * code block) to be executed
155     * (see VMParserContext::eventHandlerByName())
156     * @returns current status of the vitual machine (i.e. script succeeded,
157     * script runtime error occurred or script was suspended for
158     * some reason).
159     */
160     VMExecStatus_t exec(VMParserContext* parserContext, VMExecContext* execContext, VMEventHandler* handler);
161    
162     /**
163     * Returns built-in script function for the given function @a name. To
164     * get the implementation of the built-in message() script function for
165     * example, you would pass "message" here).
166     *
167     * This method is re-implemented by deriving classes to add more use
168     * case specific built-in functions.
169     *
170     * @param name - name of the function to be retrieved (i.e. "wait" for the
171     * built-in wait() function).
172     */
173 schoenebeck 2594 VMFunction* functionByName(const String& name) OVERRIDE;
174 schoenebeck 2727
175     /**
176 schoenebeck 3311 * Whether the passed built-in function is disabled and should thus be
177     * ignored by the parser at the passed parser context (parser state
178     * where the built-in function call occurs).
179     *
180     * @param fn - built-in function to be checked
181     * @param ctx - parser context at the position where the built-in
182     * function call is located within the script
183     */
184     bool isFunctionDisabled(VMFunction* fn, VMParserContext* ctx) OVERRIDE;
185    
186     /**
187 schoenebeck 2727 * Returns all built-in integer script variables. This method returns a
188     * STL map, where the map's key is the variable name and the map's value
189     * is the native pointer to the actual built-in variable.
190     *
191     * This method is re-implemented by deriving classes to add more use
192     * case specific built-in variables.
193     */
194 schoenebeck 2594 std::map<String,VMIntRelPtr*> builtInIntVariables() OVERRIDE;
195 schoenebeck 2727
196     /**
197     * Returns all built-in (8 bit) integer array script variables. This
198     * method returns a STL map, where the map's key is the array variable
199     * name and the map's value is the native pointer to the actual built-in
200     * array variable.
201     *
202     * This method is re-implemented by deriving classes to add more use
203     * case specific built-in array variables.
204     */
205 schoenebeck 2594 std::map<String,VMInt8Array*> builtInIntArrayVariables() OVERRIDE;
206 schoenebeck 2727
207     /**
208 schoenebeck 2948 * Returns all built-in constant integer script variables, which are
209     * constant and their final data is already available at parser time
210     * and won't change during runtime. Providing your built-in constants
211     * this way may lead to performance benefits compared to using other
212     * ways of providing built-in variables, because the script parser
213     * can perform optimizations when the script is refering to such
214     * constants.
215 schoenebeck 2727 *
216 schoenebeck 2948 * This type of built-in variable can only be read, but not be altered
217     * by scripts. This method returns a STL map, where the map's key is
218     * the variable name and the map's value is the final constant data.
219     *
220 schoenebeck 2727 * This method is re-implemented by deriving classes to add more use
221     * case specific built-in constant integers.
222     *
223 schoenebeck 2948 * @b Note: In case your built-in variable should be read-only but its
224     * value is not already available at parser time (i.e. because its
225     * value may change at runtime), then you should add it to
226     * builtInIntVariables() instead and use the macro
227     * DECLARE_VMINT_READONLY() to define the variable for read-only
228     * access by scripts.
229 schoenebeck 2727 */
230 schoenebeck 2594 std::map<String,int> builtInConstIntVariables() OVERRIDE;
231 schoenebeck 2588
232 schoenebeck 2942 /**
233     * Returns all built-in dynamic variables. This method returns a STL
234     * map, where the map's key is the dynamic variable's name and the
235     * map's value is the pointer to the actual object implementing the
236     * behavior which is actually generating the content of the dynamic
237     * variable.
238     *
239     * This method is re-implemented by deriving classes to add more use
240     * case specific built-in dynamic variables.
241     */
242     std::map<String,VMDynVar*> builtInDynamicVariables() OVERRIDE;
243    
244 schoenebeck 2974 /**
245     * Enables or disables automatic suspension of scripts by the VM.
246     * If automatic suspension is enabled then scripts are monitored
247     * regarding their execution time and in case they are execution
248     * for too long, then they are automatically suspended by the VM for
249     * a certain amount of time in order to avoid any RT instablity
250     * issues caused by bugs in the script, i.e. endless while() loops
251     * or very large scripts.
252     *
253     * Automatic suspension is enabled by default due to the aimed
254     * real-time context of this virtual machine.
255     *
256     * @param b - true: enable auto suspension [default],
257     * false: disable auto suspension
258     */
259     void setAutoSuspendEnabled(bool b = true);
260    
261     /**
262     * Returns true in case automatic suspension of scripts by the VM is
263     * enabled. See setAutoSuspendEnabled() for details.
264     *
265     * Automatic suspension is enabled by default due to the aimed
266     * real-time context of this virtual machine.
267     */
268     bool isAutoSuspendEnabled() const;
269    
270 schoenebeck 3551 /**
271     * By default (i.e. in production use) the built-in exit() function
272     * prohibits any arguments to be passed to its function by scripts. So
273     * by default, scripts trying to pass any arguments to the built-in
274     * exit() function will yield in a parser error.
275     *
276     * By calling this method the built-in exit() function will optionally
277     * accept one argument to be passed to its function call by scripts. The
278     * value of that function argument will become available by calling
279     * VMExecContext::exitResult() after execution of the script.
280     *
281     * @see VMExecContext::exitResult()
282     */
283     void setExitResultEnabled(bool b = true);
284    
285     /**
286     * Returns @c true if the built-in exit() function optionally accepts
287     * a function argument by scripts.
288     *
289     * @see setExitResultEnabled()
290     */
291     bool isExitResultEnabled() const;
292    
293 schoenebeck 2879 VMEventHandler* currentVMEventHandler(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions)
294 schoenebeck 2588 VMParserContext* currentVMParserContext(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions)
295     VMExecContext* currentVMExecContext(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions)
296 schoenebeck 2727
297 schoenebeck 2581 protected:
298 schoenebeck 2879 VMEventHandler* m_eventHandler;
299 schoenebeck 2588 ParserContext* m_parserContext;
300 schoenebeck 2974 bool m_autoSuspend;
301 schoenebeck 3551 bool m_acceptExitRes;
302 schoenebeck 2942 class CoreVMFunction_message* m_fnMessage;
303     class CoreVMFunction_exit* m_fnExit;
304     class CoreVMFunction_wait* m_fnWait;
305     class CoreVMFunction_abs* m_fnAbs;
306     class CoreVMFunction_random* m_fnRandom;
307     class CoreVMFunction_num_elements* m_fnNumElements;
308 schoenebeck 2945 class CoreVMFunction_inc* m_fnInc;
309     class CoreVMFunction_dec* m_fnDec;
310 schoenebeck 3076 class CoreVMFunction_in_range* m_fnInRange;
311 schoenebeck 2965 class CoreVMFunction_sh_left* m_fnShLeft;
312     class CoreVMFunction_sh_right* m_fnShRight;
313 schoenebeck 2970 class CoreVMFunction_min* m_fnMin;
314     class CoreVMFunction_max* m_fnMax;
315 schoenebeck 3221 class CoreVMFunction_array_equal* m_fnArrayEqual;
316     class CoreVMFunction_search* m_fnSearch;
317     class CoreVMFunction_sort* m_fnSort;
318 schoenebeck 2942 class CoreVMDynVar_NKSP_REAL_TIMER* m_varRealTimer;
319     class CoreVMDynVar_NKSP_PERF_TIMER* m_varPerfTimer;
320 schoenebeck 2581 };
321    
322     } // namespace LinuxSampler
323    
324     #endif // LS_INSTRUMENTSCRIPTVM_H

  ViewVC Help
Powered by ViewVC