Specifications of Vnano Engine
This page is the specification document of VnanoEngine class, Options, and so on.
Engine Methods
The following is the list of all methods of Vnano Engine (org.vcssl.nano.VnanoEngine class).
| Signature | void activate() |
|---|---|
| Description |
Activates this engine. By this activation, the engine become available for executing scripts. By default, the engine is activated automatically just before executing a script. However, when "AUTOMATIC_ACTIVATION_ENABLED" option is set to FALSE, the engine is NOT activated automatically. In such case, activate the engine manually at suitable timing (for details, see the description of "AUTOMATIC_ACTIVATION_ENABLED" option). In this activation step, initialization procedures of all connected plug-ins (implemented as initializeForExecution() method in each plug-in) are processed. Hence, required time of this method depends on the number of the connected plug-ins, and implementations of them. |
| Parameters | None |
| Return | None |
| Exception | VnanoException: Thrown when any error has occurred in the initialization procedure of any plug-in. |
| Signature | void deactivate() |
|---|---|
| Description |
Deactivates this engine. This deactivation canceles the state of the engine which is "activated" for executing scripts. It also performs some finalization procedures. By default, the engine is deactivated automatically just after executing a script. However, when "AUTOMATIC_ACTIVATION_ENABLED" option is set to FALSE, the engine is NOT deactivated automatically. In such case, deactivate the engine manually at suitable timing (for details, see the description of "AUTOMATIC_ACTIVATION_ENABLED" option). In this deactivation step, finalization procedures of all connected plug-ins (implemented as finalizeForTermination() method in each plug-in) are processed. Hence, required time of this method depends on the number of the connected plug-ins, and implementations of them. |
| Parameters | None |
| Return | None |
| Exception | VnanoException: Thrown when any error has occurred in the finalization procedure of any plug-in. |
| Signature | Object executeScript(String script) |
|---|---|
| Description | Executes an expression or script code specified as an argument. |
| Parameters | script: An expression or script code to be executed |
| Return | The evaluated value of the expression, or the last expression statement in script code. If there is no evaluated value, returns null. |
| Exception | VnanoException: Thrown when any error has detected for the content or the processing of the script. |
| Signature | void terminateScript() |
|---|---|
| Description | Terminates the currently running script as soon as possible. To be precise, the VirtualMachine (which is processing instructions compiled from the script) in the engine will be terminated after when the processing of a currently executed instruction has been completed, without processing remained instructions. Usually it ends in a moment, but sometimes it takes time. For example, it can't end while external function provided by a plug-in is being executed. Also, if you used this method, call "resetTerminator()" method before the next execution of a new script, otherwise the next execution will end immediately without processing any instructions (By this behavior, even when a termination-request and an execution-request from another thread are conflict, the execution will be terminated certainly). |
| Parameters | None |
| Return | None |
| Exception |
VnanoException: Thrown when any error has detected for the content or the processing of the script. Note that, if any exceptions occurred on the finalization processes of the connected plug-ins, it will be throws by the currently running executeScript(String script) method, not by this method. This method throws the exception only when it failed requesting the termination. |
| Signature | boolean isTerminatorEnabled() |
|---|---|
| Description | Returns whether the "terminator" which is the feature to terminate scripts, is enabled. Internally, this method checks the value of "TERMINATOR_ENABLED" option (disabled by default) and returns it. |
| Parameters | None |
| Return | None |
| Exception | None |
| Signature | void resetTerminator() |
|---|---|
| Description | Resets the engine which had terminated by terminateScript() method, for processing new scripts. |
| Parameters | None |
| Return | None |
| Exception | VnanoFatalException (Unchecked Exception): Thrown if this method is called in a state in which isTerminatorEnabled() returns false. |
| Signature | void connectPlugin(String bindingName, Object plugin) |
|---|---|
| Description | Connects various types of plug-ins which provides external functions/variables and so on. |
| Parameters | bindingName: A name in scripts of the variable/function/namespace provided by the connected plug-in. If the passed argument contains a white space or a character "(", the content after it will be ignored. Also, you can specify "___VNANO_AUTO_KEY" for using a valid value generated automatically. plugin: The plug-in providing external function/variable and so on. As the type of plug-ins, java.lang.reflect.Field and Method, java.lang.Class and Object, org.vcssl.connect.ExternalVariableConnectorInterface1, ExternalFunctionConnectorInterface1, ExternalNamespaceConnectorInterface1, and PermissionAuthorizerConnectorInterface1 are available. |
| Return | None |
| Exception | VnanoFatalException (Unchecked Exception): Thrown if this method is called in a state in which isTerminatorEnabled() returns false. |
| Signature | void disconnectAllPlugins() |
|---|---|
| Description | Disconnects all plug-ins. |
| Parameters | None |
| Return | None |
| Exception | VnanoException: Thrown when an exception occurred on the finalization of the plug-in to be disconnected. |
| Signature | void includeLibraryScript(String libraryScriptName, String libraryScriptContent) |
|---|---|
| Description | Add a library script which will be "include"-ed at the head of a executed script. |
| Parameters | libraryScriptName: Names of the library script (displayed in error messages) libraryScriptContent: Contents (code) of the library script |
| Return | None |
| Exception | VnanoException: Thrown when incorrect somethings have been detected for the specified library. |
| Signature | void unincludeAllLibraryScripts() |
|---|---|
| Description | Uninclude all library scripts. |
| Parameters | None |
| Return | None |
| Exception | No Exceptions will not be thrown on the current implementation, but it requires to be "catch"-ed for keeping compatibility in future. |
| Signature | void setOptionMap(Map<String,Object> optionMap) |
|---|---|
| Description | Sets options, by a Map (option map) storing names and values of options you want to set. Type of the option map is Map<String,Object>, and its keys represents option names. For details, see Option Items section. |
| Parameters | optionMap: The Map (option map) storing names and values of options |
| Return | None |
| Exception | VnanoException: Thrown if invalid option settings is detected. |
| Signature | boolean hasOptionMap() |
|---|---|
| Description | Returns whether getOptionMap() method can return a Map. |
| Parameters | None |
| Return | Returns true if getOptionMap() method can return a Map. |
| Exception | None |
| Signature | Map<String,Object> getOptionMap() |
|---|---|
| Description | Gets the Map (option map) storing names and values of options. |
| Parameters | None |
| Return | The Map (option map) storing names and values of options |
| Exception | VnanoFatalException (Unchecked Exception): Thrown if this method is called in a state in which hasOptionMap() returns false. |
| Signature | void setPermissionMap(Map<String, String> permissionMap) |
|---|---|
| Description | Sets permissions, by a Map (permission map) storing names and values of permission items you want to set. Type of the permission map is Map<String,String>, and its keys represents names of permission items. For details, see Permission Items section. |
| Parameters | permissionMap: The Map (permission map) storing names and values of permission items |
| Return | None |
| Exception | VnanoException: Thrown if invalid permission settings is detected. |
| Signature | boolean hasPermissionMap() |
|---|---|
| Description | Returns whether getPermissionMap() method can return a Map. |
| Parameters | None |
| Return | Returns true if getPermissionMap() method can return a Map. |
| Exception | None |
| Signature | Map<String,String> getPermissionMap() |
|---|---|
| Description | Gets the Map (permission map) storing names and values of permission items. |
| Parameters | None |
| Return | The Map (permission map) storing names and values of permission items. |
| Exception | VnanoFatalException (Unchecked Exception): Thrown if this method is called in a state in which hasPermissionMap() returns false. |
| Signature | boolean hasPerformanceMap() |
|---|---|
| Description | Returns whether getPerformanceMap() method can return a Map. Internally, this method checks the value of "PERFORMANCE_MONITOR_ENABLED" option (disabled by default) and returns it. |
| Parameters | None |
| Return | Returns true if getPerformanceMap() method can return a Map. |
| Exception | None |
| Signature | Map<String, Object> getPerformanceMap() |
|---|---|
| Description | Gets the Map (performance map) storing names and values of performance monitoring items. Note that, when some measured values for some monitoring items don't exist (e.g.: when any scripts are not running, or running but their performance values are not measualable yet), the returned performance map does not contain values for such monitoring items, so sometimes the returned performance map is incomplete (missing values for some items) or empty. Please be careful of the above point when you "get" measured performance values from the returned performance map. |
| Parameters | None |
| Return | The Map (performance map) storing names and values of performance monitoring items |
| Exception | VnanoFatalException (Unchecked Exception): Thrown if this method is called in a state in which hasPerformanceMap() returns false. |
Engine Options
The following is the list of all available options of Vnano Engine. The type of names is "String". Also, "Env." in the "Default Value" column means "Environment Dependent".
| Name | Type of Value | Default Value | Description |
|---|---|---|---|
| LOCALE | java.util. Locale |
Env. | The locale to switch the language of error messages. |
| MAIN_SCRIPT_NAME | String | "main script" | The name of the execution target script. |
| MAIN_SCRIPT_DIRECTORY | String | "." | The path of the directory (folder) in which the execution target script is locating. |
| EVAL_INT_LITERAL_AS_FLOAT | Boolean | FALSE | An option to regard integer literals as float type in the execution/evaluation target expressions and scripts (excepting library scripts). |
| EVAL_ONLY_EXPRESSION | Boolean | FALSE | An option to restrict types of available statements in the execution target scripts (excepting library scripts) to only "expression". |
| EVAL_ONLY_FLOAT | Boolean | FALSE | An option to restrict available data types of operators/operands in the execution target scripts (excepting library scripts) to only "float". |
| ACCELERATOR_ENABLED | Boolean | TRUE | An option to enable/disable the Accelerator (org.vcssl.nano.vm.accelerator.Accelerator), which is the high-speed virtual processor implementation in the VM. |
| ACCELERATOR_OPTIMIZATION_LEVEL | Integer | 3 | An option to control the optimization level of processing in the Accelerator. The value is: 0: Dont't optimize. 1: Optimize data accesses for reducing overhead costs (e.g.: caching operand/operated values). 2: In addition to the above, optimize instructions with keeping code structures (e.g.: join multiple instructions by reordering them). 3: In addition to the above, optimize with modifying code structures (e.g.: inline expansion). |
| TERMINATOR_ENABLED | Boolean | FALSE | An option to enable/disable the feature for terminating a running script. If you enable this option, you become to able to terminate a running script BY OPERATION OF THE SCRIPT ENGINE, but the maximum numerical operating speed (and so on) may decreases slightly. Probably, for most cases, users hardly can recognize the decreasing of the operating speed caused by this option. However, for highly optimized numerical computation scripts, the operating speed may decrease about 10% or more. Note that, the script will be terminated when all procedures in the script completed, or when any errors occurred in the script, or when exit() function is called in the script, regardless whether this option is enabled or disabled. |
| PERFORMANCE_MONITOR_ENABLED | Boolean | FALSE | An option to enable/disable the performance monitor. If you enable this option, you become to get performance monitoring values of the engine, but the maximum numerical operating speed (and so on) may decreases to some extent. Probably, for most cases, decreasing of the operating speed caused by this option is not so heavy. However, for highly optimized numerical computation scripts, the operating speed may decrease about 25% or more. |
| DUMPER_ENABLED | Boolean | FALSE | An option to dump states and intermediate representations in the compiler, VM, etc. |
| DUMPER_TARGET | String | "ALL" | Specify the target of to dump. Values are the followings: "ALL": Dump all contents. "INPUTTED_CODE": Dump the inutted script code. "PREPROCESSED_CODE": Dump pre-processed script code, from which comments are removed. "TOKEN": Dump tokens, which are output of the LexicalAnalyzer. "PARSED_AST": Dump the Abstract Syntax Tree (AST), which is the output of the Parser. "ANALYZED_AST": Dump the semantic-analyzed AST, which is the output of the SemanticAnalyzer. "ASSEMBLY_CODE": Dump the VRIL code, which is the compilation result, output of the CodeGenerator. "OBJECT_CODE": Dump the VM object code (unoptimized), which is output of the Assembler. "ACCELERATOR_CODE": Dump optimized instructions for the Accelerator, which are output of the AcceleratorOptimizationUnit. "ACCELERATOR_STATE": Dump the internal state (dispatchments of execution units, and so on) of the Accelerator. |
| DUMPER_STREAM | java.io. PrintStream |
System.out | Specify the stream to output dumped contents. |
| RUNNING_ENABLED | Boolean | TRUE | An option to switch whether execute script or don't. This option might be useful when you want to dump the compiled result for debugging but don't want to run it. |
| AUTOMATIC_ACTIVATION_ENABLED | Boolean | TRUE | An option to switch whether activate/deactivate the Vnano engine automatically before/after executing a script ("automatic activation" feature). This option is enabled by default so that users can execute scripts any time. However, activations/deactivations of the engine entail some overhead costs. Especially when the engine repetitively executes scripts in high frequency, this "activation costs" may result serious degradation of processing speed, if this option is enabled. In such case, disable this option, and activate/deactivate the engine manually at suitable timing (typically before/after a set of repetitive executions). |
| UI_MODE | String | "GUI" | Specify the mode of UI for inputting/outputting values and so on. As the value, specify "GUI" or "CUI". The default value is "GUI", but it will be set to "CUI" automatically when you execute the Vnano engine in the command-line mode. This option is referred by I/O plug-ins if they are connected. |
| ENVIRONMENT_EOL | String | Env. | Specify the default line-feed code on the environment. This option is referred by plug-ins providing environment-dependent values, if they are connected. |
| FILE_IO_EOL | String | Env. | Specify the default line-feed code for file I/O. This option is referred by I/O plug-ins if they are connected. |
| TERMINAL_IO_EOL | String | Env. | Specify the default line-feed code for terminal I/O. This option is referred by I/O plug-ins if they are connected. |
| FILE_IO_ENCODING | String | "UTF-8" | Specify the name of the default encoding for writing to / reading files in scripts. This option is referred by I/O plug-ins if they are connected. |
| STDIN_STREAM | Java.io. InputStream |
System.in | Specify the stream for standard input used when the option TERMINAL_IO_UI is set to "CUI". This option is referred by I/O plug-ins if they are connected. |
| STDOUT_STREAM | Java.io. PrintStream |
System.out | Specify the stream for standard output used when the option TERMINAL_IO_UI is set to "CUI". This option is referred by I/O plug-ins if they are connected. |
| STDERR_STREAM | Java.io. PrintStream |
System.err | Specify the stream for standard error output when the option TERMINAL_IO_UI is set to "CUI". This option is referred by I/O plug-ins if they are connected. |
Permission Items
The following is the list of permission items. The type of names is "String". The type of values is also "String", and it takes either "DENY", "ALLOW", or "ASK". A permission value "ASK" means that: "determine whether allow or deny by asking the user". By defailt, all values are set to "DENY".
| Name | Description |
|---|---|
| PROGRAM_EXIT | The permission to exit the currently executed program (script). |
| PROGRAM_RESET | The permission to reset/restart the currently executed program (script). |
| PROGRAM_CHANGE | The permission to change the currently executed program (script). |
| SYSTEM_PROCESS | The permission to execute commands or other programs through the Operating System and so on. |
| DIRECTORY_CREATE | The permission to create a new directory (folder). |
| DIRECTORY_DELETE | The permission to delete a directory (folder). |
| DIRECTORY_LIST | The permission to get the list of files in a directory (folder). |
| FILE_CREATE | The permission to create a new file. |
| FILE_DELETE | The permission to delete a file. |
| FILE_WRITE | The permission to write contents of a file. |
| FILE_READ | The permission to read contents of a file. |
| FILE_OVERWRITE | The permission to overwrite contents of a file. |
| FILE_INFORMATION_CHANGE | The permission to change information (last modified date, and so on) of a file. |
| ALL | The name of the meta item representing all permission items. |
| NONE | The name of the meta item representing no permission item. |
| DEFAULT | The name of the meta item storing the default permission value. For permission items of which values are not specified explicitly, a default value (e.g. "DENY") will be set automatically. You can change that default value by setting the value to this meta permission item. For example, if you set the value "ASK" to this permission item "DEFAULT", the script engine will ask to the user when non-specified permissions are required. |
