src/scriptvm/ScriptVM.h

/*
 * Copyright (c) 2014-2015 Christian Schoenebeck
 *
 * http://www.linuxsampler.org
 *
 * This file is part of LinuxSampler and released under the same terms.
 * See README file for details.
 */

#ifndef LS_SCRIPTVM_H
#define LS_SCRIPTVM_H

#include <iostream>
#include <vector>

#include "../common/global.h"
#include "common.h"
#include "CoreVMFunctions.h"

namespace LinuxSampler {

    class ParserContext;
    class ExecContext;

    /** @brief Core virtual machine for real-time instrument scripts.
     *
     * This is the core of the virtual machine and main entry class, used for
     * running real-time instrument scripts. This VM core encompasses the
     * instrument script parser, generalized virtual machine and very generic
     * built-in script functions. Thus this class only provides functionalities
     * which are yet independent of the actual purpose the virtual machine is
     * going to be used for.
     *
     * The actual use case specific functionalites (i.e. MIDI processing) is
     * then implemented by sampler engines' VM classes which are derived from
     * this generalized ScriptVM class.
     *
     * Typical usage of this class:
     *
     * - 1. Create an instance of this ScriptVM class (or of one of its deriving
     *      classes).
     * - 2. Load a script by passing its source code to method loadScript(),
     *      which will return the parsed represenation of the script.
     * - 3. Create a VM execution context by calling createExecContext().
     * - 4. Execute the script by calling method exec().
     *
     * This class is re-entrant safe, but not thread safe. So you can share one
     * instance of this class between multiple (native) threads, but you @b must
     * @b not execute methods of the same class instance simultaniously from
     * different (native) threads. If you want to execute scripts simultaniously
     * multi threaded, then create a separate ScriptVM instance for each
     * (native) thread. Also note that one VMParserContext instance is tied to
     * exactly one ScriptVM instance. So you @b must @b not create a
     * VMParserContext with one ScriptVM instance and run it with a different
     * ScriptVM instance!
     */
    class ScriptVM : public VMFunctionProvider {
    public:
        ScriptVM();
        virtual ~ScriptVM();

        /**
         * Loads a script given by its source code (passed as argument @a s to
         * this method) and returns the parsed represenation of that script.
         * After calling this method you must check the returned VMParserContext
         * object whether there had been any parser errors. If there were no
         * parser errors, you may pass the VMParserContext object to method
         * exec() for actually executing the script.
         *
         * @param s - entire source code of the script to be loaded
         * @returns parsed represenation of the script
         */
        VMParserContext* loadScript(const String& s);

        /**
         * Same as above's loadScript() 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 parsed represenation of the script
         */
        VMParserContext* loadScript(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.
         *
         * @param context - parsed represenation of the script
         */
        void dumpParsedScript(VMParserContext* context);

        /**
         * Creates a so called VM exceution context for a specific, already
         * parsed script (provided by argument @a parserContext). Due to the
         * general real-time design of this virtual machine, the VM execution
         * context differs for every script. So you must (re)create the
         * execution context for each script being loaded.
         */
        VMExecContext* createExecContext(VMParserContext* parserContext);

        /**
         * Execute a script by virtual machine. Since scripts are event-driven,
         * you actually execute only one specific event handler block (i.e. a
         * "on note ... end on" code block) by calling this method (not the
         * entire script), and hence you must provide one precise handler of the
         * script to be executed by this method.
         *
         * 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
         * 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.
         *
         * @param parserContext - parsed represenation of the script
         * @param execContext - VM execution context (see createExecContext())
         * @param handler - precise event handler (i.e. "on note ... end on"
         *                  code block) to be executed
         *                  (see VMParserContext::eventHandlerByName())
         * @returns current status of the vitual machine (i.e. script succeeded,
         *          script runtime error occurred or script was suspended for
         *          some reason).
         */
        VMExecStatus_t exec(VMParserContext* parserContext, VMExecContext* execContext, VMEventHandler* handler);

        /**
         * Returns built-in script function for the given function @a name. To
         * get the implementation of the built-in message() script function for
         * example, you would pass "message" here).
         *
         * This method is re-implemented by deriving classes to add more use
         * case specific built-in functions.
         *
         * @param name - name of the function to be retrieved (i.e. "wait" for the 
         *               built-in wait() function).
         */
        VMFunction* functionByName(const String& name) 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.
         *
         * This method is re-implemented by deriving classes to add more use
         * case specific built-in variables.
         */
        std::map<String,VMIntRelPtr*> builtInIntVariables() OVERRIDE;

        /**
         * Returns all built-in (8 bit) integer array script variables. This
         * method returns a STL map, where the map's key is the array variable
         * name and the map's value is the native pointer to the actual built-in
         * array variable.
         *
         * This method is re-implemented by deriving classes to add more use
         * case specific built-in array variables.
         */
        std::map<String,VMInt8Array*> 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.
         *
         * 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.
         */
        std::map<String,int> builtInConstIntVariables() OVERRIDE;

        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:
        ParserContext* m_parserContext;
        CoreVMFunction_message fnMessage;
        CoreVMFunction_exit fnExit;
        CoreVMFunction_wait fnWait;
        CoreVMFunction_abs fnAbs;
        CoreVMFunction_random fnRandom;
        CoreVMFunction_num_elements fnNumElements;
    };

} // namespace LinuxSampler

#endif // LS_INSTRUMENTSCRIPTVM_H
1	schoenebeck	2581	/*
2	schoenebeck	2727	* Copyright (c) 2014-2015 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			#include "CoreVMFunctions.h"
19
20			namespace LinuxSampler {
21
22			class ParserContext;
23	schoenebeck	2588	class ExecContext;
24	schoenebeck	2581
25	schoenebeck	2594	/** @brief Core virtual machine for real-time instrument scripts.
26			*
27	schoenebeck	2727	* 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	schoenebeck	2594	*
34			* The actual use case specific functionalites (i.e. MIDI processing) is
35	schoenebeck	2727	* then implemented by sampler engines' VM classes which are derived from
36			* this generalized ScriptVM class.
37	schoenebeck	2594	*
38	schoenebeck	2727	* 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	schoenebeck	2594	* 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	schoenebeck	2581	class ScriptVM : public VMFunctionProvider {
58			public:
59			ScriptVM();
60			virtual ~ScriptVM();
61	schoenebeck	2727
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	schoenebeck	2588	VMParserContext* loadScript(const String& s);
74	schoenebeck	2727
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	schoenebeck	2588	VMParserContext* loadScript(std::istream* is);
84	schoenebeck	2727
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	schoenebeck	2588	void dumpParsedScript(VMParserContext* context);
93	schoenebeck	2727
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	schoenebeck	2588	VMExecContext* createExecContext(VMParserContext* parserContext);
102	schoenebeck	2727
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	schoenebeck	2594	VMFunction* functionByName(const String& name) OVERRIDE;
141	schoenebeck	2727
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	schoenebeck	2594	std::map<String,VMIntRelPtr*> builtInIntVariables() OVERRIDE;
151	schoenebeck	2727
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	schoenebeck	2594	std::map<String,VMInt8Array*> builtInIntArrayVariables() OVERRIDE;
162	schoenebeck	2727
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	schoenebeck	2594	std::map<String,int> builtInConstIntVariables() OVERRIDE;
179	schoenebeck	2588
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	schoenebeck	2727
183	schoenebeck	2581	protected:
184	schoenebeck	2588	ParserContext* m_parserContext;
185	schoenebeck	2581	CoreVMFunction_message fnMessage;
186			CoreVMFunction_exit fnExit;
187			CoreVMFunction_wait fnWait;
188	schoenebeck	2619	CoreVMFunction_abs fnAbs;
189			CoreVMFunction_random fnRandom;
190			CoreVMFunction_num_elements fnNumElements;
191	schoenebeck	2581	};
192
193			} // namespace LinuxSampler
194
195			#endif // LS_INSTRUMENTSCRIPTVM_H