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

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

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

revision 2581 by schoenebeck, Fri May 30 12:48:05 2014 UTC revision 2885 by schoenebeck, Fri Apr 22 15:37:45 2016 UTC
# Line 1  Line 1 
1  /*  /*
2   * Copyright (c) 2014 Christian Schoenebeck   * Copyright (c) 2014-2016 Christian Schoenebeck
3   *   *
4   * http://www.linuxsampler.org   * http://www.linuxsampler.org
5   *   *
# Line 15  Line 15 
15    
16  #include "../common/global.h"  #include "../common/global.h"
17  #include "common.h"  #include "common.h"
 #include "CoreVMFunctions.h"  
18    
19  namespace LinuxSampler {  namespace LinuxSampler {
20    
21      class ParserContext;      class ParserContext;
22        class ExecContext;
23        class CoreVMFunction_message;
24        class CoreVMFunction_exit;
25        class CoreVMFunction_wait;
26        class CoreVMFunction_abs;
27        class CoreVMFunction_random;
28        class CoreVMFunction_num_elements;
29    
30        /** @brief Core virtual machine for real-time instrument scripts.
31         *
32         * This is the core of the virtual machine and main entry class, used for
33         * running real-time instrument scripts. This VM core encompasses the
34         * instrument script parser, generalized virtual machine and very generic
35         * built-in script functions. Thus this class only provides functionalities
36         * which are yet independent of the actual purpose the virtual machine is
37         * going to be used for.
38         *
39         * The actual use case specific functionalites (i.e. MIDI processing) is
40         * then implemented by sampler engines' VM classes which are derived from
41         * this generalized ScriptVM class.
42         *
43         * Typical usage of this class:
44         *
45         * - 1. Create an instance of this ScriptVM class (or of one of its deriving
46         *      classes).
47         * - 2. Load a script by passing its source code to method loadScript(),
48         *      which will return the parsed representation of the script.
49         * - 3. Create a VM execution context by calling createExecContext().
50         * - 4. Execute the script by calling method exec().
51         *
52         * This class is re-entrant safe, but not thread safe. So you can share one
53         * instance of this class between multiple (native) threads, but you @b must
54         * @b not execute methods of the same class instance simultaniously from
55         * different (native) threads. If you want to execute scripts simultaniously
56         * multi threaded, then create a separate ScriptVM instance for each
57         * (native) thread. Also note that one VMParserContext instance is tied to
58         * exactly one ScriptVM instance. So you @b must @b not create a
59         * VMParserContext with one ScriptVM instance and run it with a different
60         * ScriptVM instance!
61         */
62      class ScriptVM : public VMFunctionProvider {      class ScriptVM : public VMFunctionProvider {
63      public:      public:
64          ScriptVM();          ScriptVM();
65          virtual ~ScriptVM();          virtual ~ScriptVM();
66          void loadScript(const String& s);  
67          void loadScript(std::istream* is);          /**
68          std::vector<ParserIssue> issues() const;           * Loads a script given by its source code (passed as argument @a s to
69          std::vector<ParserIssue> errors() const;           * this method) and returns the parsed representation of that script.
70          std::vector<ParserIssue> warnings() const;           * After calling this method you must check the returned VMParserContext
71          void dumpParsedScript();           * object whether there had been any parser errors. If there were no
72          VMExecContext* createExecContext();           * parser errors, you may pass the VMParserContext object to method
73          VMEventHandler* eventHandler(uint index);           * exec() for actually executing the script.
74          VMEventHandler* eventHandlerByName(const String& name);           *
75          VMExecStatus_t exec(VMEventHandler* handler, VMExecContext* execContex);           * @param s - entire source code of the script to be loaded
76          VMExecContext* currentVMExecContext();           * @returns parsed representation of the script
77          VMFunction* functionByName(const String& name);           */
78            VMParserContext* loadScript(const String& s);
79    
80            /**
81             * Same as above's loadScript() method, but this one reads the script's
82             * source code from an input stream object (i.e. stdin or a file).
83             *
84             * @param is - input stream from which the entire source code of the
85             *             script is to be read and loaded from
86             * @returns parsed representation of the script
87             */
88            VMParserContext* loadScript(std::istream* is);
89    
90            /**
91             * Parses a script's source code (passed as argument @a s to this
92             * method), splits that input up in its individual tokens (i.e.
93             * keyword, variable name, event name, etc.) and returns all those
94             * tokens, for the purpose that the caller can provide syntax syntax
95             * highlighting for the passed script.
96             *
97             * This method is actually not used by the sampler at all, it is rather
98             * provided for external script editor applications, to provide them a
99             * convenient backend for parsing scripts and providing syntax
100             * highlighting.
101             *
102             * @returns recognized tokens of passed script's source code
103             */
104            std::vector<VMSourceToken> syntaxHighlighting(const String& s);
105    
106            /**
107             * Same as above's syntaxHighlighting() method, but this one reads the
108             * script's source code from an input stream object (i.e. stdin or a
109             * file).
110             *
111             * @param is - input stream from which the entire source code of the
112             *             script is to be read and loaded from
113             * @returns recognized tokens of passed script's source code
114             */
115            std::vector<VMSourceToken> syntaxHighlighting(std::istream* is);
116    
117            /**
118             * Dumps the translated tree of the already parsed script, given by
119             * argument @a context, to stdout. This method is for debugging purposes
120             * only.
121             *
122             * @param context - parsed representation of the script
123             * @see loadScript()
124             */
125            void dumpParsedScript(VMParserContext* context);
126    
127            /**
128             * Creates a so called VM exceution context for a specific, already
129             * parsed script (provided by argument @a parserContext). Due to the
130             * general real-time design of this virtual machine, the VM execution
131             * context differs for every script. So you must (re)create the
132             * execution context for each script being loaded.
133             *
134             * @param parserContext - parsed representation of the script
135             * @see loadScript()
136             */
137            VMExecContext* createExecContext(VMParserContext* parserContext);
138    
139            /**
140             * Execute a script by virtual machine. Since scripts are event-driven,
141             * you actually execute only one specific event handler block (i.e. a
142             * "on note ... end on" code block) by calling this method (not the
143             * entire script), and hence you must provide one precise handler of the
144             * script to be executed by this method.
145             *
146             * This method usually blocks until the entire script event handler
147             * block has been executed completely. It may however also return before
148             * completion if either a) a script runtime error occurred or b) the
149             * script was suspended by the VM (either because script execution
150             * exceeded a certain limit of time or the script called the built-in
151             * wait() function). You must check the return value of this method to
152             * find out which case applies.
153             *
154             * @param parserContext - parsed representation of the script (see loadScript())
155             * @param execContext - VM execution context (see createExecContext())
156             * @param handler - precise event handler (i.e. "on note ... end on"
157             *                  code block) to be executed
158             *                  (see VMParserContext::eventHandlerByName())
159             * @returns current status of the vitual machine (i.e. script succeeded,
160             *          script runtime error occurred or script was suspended for
161             *          some reason).
162             */
163            VMExecStatus_t exec(VMParserContext* parserContext, VMExecContext* execContext, VMEventHandler* handler);
164    
165            /**
166             * Returns built-in script function for the given function @a name. To
167             * get the implementation of the built-in message() script function for
168             * example, you would pass "message" here).
169             *
170             * This method is re-implemented by deriving classes to add more use
171             * case specific built-in functions.
172             *
173             * @param name - name of the function to be retrieved (i.e. "wait" for the
174             *               built-in wait() function).
175             */
176            VMFunction* functionByName(const String& name) OVERRIDE;
177    
178            /**
179             * Returns all built-in integer script variables. This method returns a
180             * STL map, where the map's key is the variable name and the map's value
181             * is the native pointer to the actual built-in variable.
182             *
183             * This method is re-implemented by deriving classes to add more use
184             * case specific built-in variables.
185             */
186            std::map<String,VMIntRelPtr*> builtInIntVariables() OVERRIDE;
187    
188            /**
189             * Returns all built-in (8 bit) integer array script variables. This
190             * method returns a STL map, where the map's key is the array variable
191             * name and the map's value is the native pointer to the actual built-in
192             * array variable.
193             *
194             * This method is re-implemented by deriving classes to add more use
195             * case specific built-in array variables.
196             */
197            std::map<String,VMInt8Array*> builtInIntArrayVariables() OVERRIDE;
198    
199            /**
200             * Returns all built-in constant integer script variables, which can
201             * only be read, but not be altered by scripts. This method returns a
202             * STL map, where the map's key is the variable name and the map's value
203             * is the native pointer to the actual built-in constant variable.
204             *
205             * This method is re-implemented by deriving classes to add more use
206             * case specific built-in constant integers.
207             *
208             * @b Note: the term "constant" is a bit misleading here, since
209             * built-in constant integer variables may indeed change, i.e. for
210             * built-in constant integers which i.e. reflect some kind of status of
211             * the sampler. So rather see them as "read only" variables, not as
212             * being actually consistent in time.
213             */
214            std::map<String,int> builtInConstIntVariables() OVERRIDE;
215    
216            VMEventHandler* currentVMEventHandler(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions)
217            VMParserContext* currentVMParserContext(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions)
218            VMExecContext* currentVMExecContext(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions)
219    
220      protected:      protected:
221          ParserContext* m_context;          VMEventHandler* m_eventHandler;
222          CoreVMFunction_message fnMessage;          ParserContext* m_parserContext;
223          CoreVMFunction_exit fnExit;          CoreVMFunction_message* m_fnMessage;
224          CoreVMFunction_wait fnWait;          CoreVMFunction_exit* m_fnExit;
225            CoreVMFunction_wait* m_fnWait;
226            CoreVMFunction_abs* m_fnAbs;
227            CoreVMFunction_random* m_fnRandom;
228            CoreVMFunction_num_elements* m_fnNumElements;
229      };      };
230    
231  } // namespace LinuxSampler  } // namespace LinuxSampler
Legend:
Removed from v.2581  
changed lines
  Added in v.2885
  ViewVC Help
Powered by ViewVC