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