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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2727 - (show annotations) (download) (as text)
Tue Mar 31 17:46:11 2015 UTC (9 years ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 8886 byte(s)
- Just added API doc comments to Script VM code.

1 /*
2 * Copyright (c) 2014-2015 Christian Schoenebeck
3 *
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 #include "CoreVMFunctions.h"
19
20 namespace LinuxSampler {
21
22 class ParserContext;
23 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 represenation 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 {
58 public:
59 ScriptVM();
60 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 represenation 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 represenation of the script
72 */
73 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 represenation of the script
82 */
83 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 represenation of the script
91 */
92 void dumpParsedScript(VMParserContext* context);
93
94 /**
95 * Creates a so called VM exceution context for a specific, already
96 * parsed script (provided by argument @a parserContext). Due to the
97 * general real-time design of this virtual machine, the VM execution
98 * context differs for every script. So you must (re)create the
99 * execution context for each script being loaded.
100 */
101 VMExecContext* createExecContext(VMParserContext* parserContext);
102
103 /**
104 * Execute a script by virtual machine. Since scripts are event-driven,
105 * you actually execute only one specific event handler block (i.e. a
106 * "on note ... end on" code block) by calling this method (not the
107 * entire script), and hence you must provide one precise handler of the
108 * script to be executed by this method.
109 *
110 * This method usually blocks until the entire script event handler
111 * block has been executed completely. It may however also return before
112 * completion if either a) a script runtime error occurred or b) the
113 * script was suspened by the VM (either because script execution
114 * exceeded a certain limit of time or the script called the built-in
115 * wait() function). You must check the return value of this method to
116 * find out which case applies.
117 *
118 * @param parserContext - parsed represenation of the script
119 * @param execContext - VM execution context (see createExecContext())
120 * @param handler - precise event handler (i.e. "on note ... end on"
121 * code block) to be executed
122 * (see VMParserContext::eventHandlerByName())
123 * @returns current status of the vitual machine (i.e. script succeeded,
124 * script runtime error occurred or script was suspended for
125 * some reason).
126 */
127 VMExecStatus_t exec(VMParserContext* parserContext, VMExecContext* execContext, VMEventHandler* handler);
128
129 /**
130 * Returns built-in script function for the given function @a name. To
131 * get the implementation of the built-in message() script function for
132 * example, you would pass "message" here).
133 *
134 * This method is re-implemented by deriving classes to add more use
135 * case specific built-in functions.
136 *
137 * @param name - name of the function to be retrieved (i.e. "wait" for the
138 * built-in wait() function).
139 */
140 VMFunction* functionByName(const String& name) OVERRIDE;
141
142 /**
143 * Returns all built-in integer script variables. This method returns a
144 * STL map, where the map's key is the variable name and the map's value
145 * is the native pointer to the actual built-in variable.
146 *
147 * This method is re-implemented by deriving classes to add more use
148 * case specific built-in variables.
149 */
150 std::map<String,VMIntRelPtr*> builtInIntVariables() OVERRIDE;
151
152 /**
153 * Returns all built-in (8 bit) integer array script variables. This
154 * method returns a STL map, where the map's key is the array variable
155 * name and the map's value is the native pointer to the actual built-in
156 * array variable.
157 *
158 * This method is re-implemented by deriving classes to add more use
159 * case specific built-in array variables.
160 */
161 std::map<String,VMInt8Array*> builtInIntArrayVariables() OVERRIDE;
162
163 /**
164 * Returns all built-in constant integer script variables, which can
165 * only be read, but not be altered by scripts. This method returns a
166 * STL map, where the map's key is the variable name and the map's value
167 * is the native pointer to the actual built-in constant variable.
168 *
169 * This method is re-implemented by deriving classes to add more use
170 * case specific built-in constant integers.
171 *
172 * @b Note: the term "constant" is a bit misleading here, since
173 * built-in constant integer variables may indeed change, i.e. for
174 * built-in constant integers which i.e. reflect some kind of status of
175 * the sampler. So rather see them as "read only" variables, not as
176 * being actually consistent in time.
177 */
178 std::map<String,int> builtInConstIntVariables() OVERRIDE;
179
180 VMParserContext* currentVMParserContext(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions)
181 VMExecContext* currentVMExecContext(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions)
182
183 protected:
184 ParserContext* m_parserContext;
185 CoreVMFunction_message fnMessage;
186 CoreVMFunction_exit fnExit;
187 CoreVMFunction_wait fnWait;
188 CoreVMFunction_abs fnAbs;
189 CoreVMFunction_random fnRandom;
190 CoreVMFunction_num_elements fnNumElements;
191 };
192
193 } // namespace LinuxSampler
194
195 #endif // LS_INSTRUMENTSCRIPTVM_H

  ViewVC Help
Powered by ViewVC