Struct quickjs_runtime::esruntime::EsRuntime

pub struct EsRuntime { /* fields omitted */ }

EsRuntime is the main public struct representing a JavaScript runtime. You can construct a new EsRuntime by using the EsRuntimeBuilder struct

Example

use quickjs_runtime::esruntimebuilder::EsRuntimeBuilder;
let rt = EsRuntimeBuilder::new().build();

Implementations

impl EsRuntime

pub fn get_todo_count(&self) -> usize

get the number of todos in the event queue

pub fn builder() -> EsRuntimeBuilder

pub fn add_task<C>(&self, task: C) where
    C: FnOnce() + Send + 'static, 

this can be used to run a function in the event_queue thread for the QuickJSRuntime without borrowing the q_js_rt

pub fn exe_task<C, R: Send + 'static>(&self, task: C) -> R where
    C: FnOnce() -> R + Send + 'static, 

this can be used to run a function in the event_queue thread for the QuickJSRuntime without borrowing the q_js_rt

pub async fn eval(&self, script: EsScript) -> Result<EsValueFacade, EsError>

Evaluate a script asynchronously

pub fn eval_sync(&self, script: EsScript) -> Result<EsValueFacade, EsError>

Evaluate a script and return the result synchronously

example

use quickjs_runtime::esruntimebuilder::EsRuntimeBuilder;
use quickjs_runtime::esscript::EsScript;
let rt = EsRuntimeBuilder::new().build();
let script = EsScript::new("my_file.es", "(9 * 3);");
let res = rt.eval_sync(script).ok().expect("script failed");
assert_eq!(res.get_i32(), 27);

pub async fn gc(&self)

run the garbage collector asynchronously

pub fn gc_sync(&self)

run the garbage collector and wait for it to be done

pub fn call_function_sync(
    &self,
    namespace: Vec<&'static str>,
    func_name: &str,
    arguments: Vec<EsValueFacade>
) -> Result<EsValueFacade, EsError>

call a function in the engine and await the result

example

use quickjs_runtime::esruntimebuilder::EsRuntimeBuilder;
use quickjs_runtime::esscript::EsScript;
use quickjs_runtime::es_args;
use quickjs_runtime::esvalue::EsValueConvertible;
use quickjs_runtime::esvalue::EsValueFacade;
let rt = EsRuntimeBuilder::new().build();
let script = EsScript::new("my_file.es", "this.com = {my: {methodA: function(a, b, someStr, someBool){return a*b;}}};");
rt.eval_sync(script).ok().expect("script failed");
let res = rt.call_function_sync(vec!["com", "my"], "methodA", vec![7i32.to_es_value_facade(), 5i32.to_es_value_facade(), "abc".to_string().to_es_value_facade(), true.to_es_value_facade()]).ok().expect("func failed");
assert_eq!(res.get_i32(), 35);

pub fn clone_inner(&self) -> Arc<EsRuntimeInner>

pub async fn call_function(
    &self,
    namespace: Vec<&'static str>,
    func_name: String,
    arguments: Vec<EsValueFacade>
) -> Result<EsValueFacade, EsError>

call a function in the engine asynchronously N.B. func_name is not a &str because of https://github.com/rust-lang/rust/issues/56238 (i think)

example

use quickjs_runtime::esruntimebuilder::EsRuntimeBuilder;
use quickjs_runtime::esscript::EsScript;
use quickjs_runtime::esvalue::EsValueConvertible;
let rt = EsRuntimeBuilder::new().build();
let script = EsScript::new("my_file.es", "this.com = {my: {methodA: function(a, b){return a*b;}}};");
rt.eval_sync(script).ok().expect("script failed");
rt.call_function(vec!["com", "my"], "methodA".to_string(), vec![7.to_es_value_facade(), 5.to_es_value_facade()]);

pub async fn eval_module(&self, script: EsScript)

evaluate a module, you need if you want to compile a script that contains static imports e.g.

import {util} from 'file.mes';
console.log(util(1, 2, 3));

please note that the module is cached under the absolute path you passed in the EsScript object and thus you should take care to make the path unique (hence the absolute_ name) also to use this you need to build the EsRuntime with a module loader closure

example

use quickjs_runtime::esruntimebuilder::EsRuntimeBuilder;
use quickjs_runtime::esscript::EsScript;
use quickjs_runtime::esvalue::EsValueConvertible;
use quickjs_runtime::quickjsruntime::ScriptModuleLoader;
struct TestModuleLoader {}
impl ScriptModuleLoader for TestModuleLoader {
    fn normalize_path(&self,ref_path: &str,path: &str) -> Option<String> {
        Some(path.to_string())
    }

    fn load_module(&self,absolute_path: &str) -> String {
        "export const util = function(a, b, c){return a+b+c;};".to_string()
    }
}
let rt = EsRuntimeBuilder::new().script_module_loader(Box::new(TestModuleLoader{})).build();
let script = EsScript::new("/opt/files/my_module.mes", "import {util} from 'other_module.mes';\n
console.log(util(1, 2, 3));");
rt.eval_module(script);

pub fn eval_module_sync(
    &self,
    script: EsScript
) -> Result<EsValueFacade, EsError>

evaluate a module and return result synchronously

pub fn add_to_event_queue<C, R: Send + 'static>(
    &self,
    consumer: C
) -> impl Future<Output = R> where
    C: FnOnce(&QuickJsRuntime) -> R + Send + 'static, 

this is how you add a closure to the worker thread which has an instance of the QuickJsRuntime this will run asynchronously

example

use quickjs_runtime::esruntimebuilder::EsRuntimeBuilder;
let rt = EsRuntimeBuilder::new().build();
rt.add_to_event_queue(|q_js_rt| {
    // here you are in the worker thread and you can use the quickjs_utils
    q_js_rt.gc();
});

pub fn add_to_event_queue_void<C>(&self, consumer: C) where
    C: FnOnce(&QuickJsRuntime) + Send + 'static, 

pub fn add_to_event_queue_sync<C, R>(&self, consumer: C) -> R where
    C: FnOnce(&QuickJsRuntime) -> R + Send + 'static,
    R: Send + 'static, 

this is how you add a closure to the worker thread which has an instance of the QuickJsRuntime this will run and return synchronously

example

use quickjs_runtime::esruntimebuilder::EsRuntimeBuilder;
use quickjs_runtime::esscript::EsScript;
use quickjs_runtime::quickjs_utils::primitives;
let rt = EsRuntimeBuilder::new().build();
let res = rt.add_to_event_queue_sync(|q_js_rt| {
    let q_ctx = q_js_rt.get_main_context();
    // here you are in the worker thread and you can use the quickjs_utils
    let val_ref = q_ctx.eval(EsScript::new("test.es", "(11 * 6);")).ok().expect("script failed");
    primitives::to_i32(&val_ref).ok().expect("could not get i32")
});
assert_eq!(res, 66);

pub fn set_function<F>(
    &self,
    namespace: Vec<&'static str>,
    name: &str,
    function: F
) -> Result<(), EsError> where
    F: Fn(&QuickJsContext, Vec<EsValueFacade>) -> Result<EsValueFacade, EsError> + Send + 'static, 

this adds a rust function to JavaScript, it is added for all current and future contexts

Example

use quickjs_runtime::esruntimebuilder::EsRuntimeBuilder;
use quickjs_runtime::esscript::EsScript;
use quickjs_runtime::quickjs_utils::primitives;
use quickjs_runtime::esvalue::{EsValueFacade, EsValueConvertible};
let rt = EsRuntimeBuilder::new().build();
rt.set_function(vec!["com", "mycompany", "util"], "methodA", |q_ctx, args: Vec<EsValueFacade>|{
    let a = args[0].get_i32();
    let b = args[1].get_i32();
    Ok((a * b).to_es_value_facade())
});
let res = rt.eval_sync(EsScript::new("test.es", "let a = com.mycompany.util.methodA(13, 17); a * 2;")).ok().expect("script failed");
assert_eq!(res.get_i32(), (13*17*2));

pub fn add_helper_task<T>(task: T) where
    T: FnOnce() + Send + 'static, 

add a task the the “helper” thread pool

pub fn add_helper_task_async<R: Send + 'static, T: Future<Output = R> + Send + 'static>(
    task: T
) -> impl Future<Output = Result<R, JoinError>>

add an async task the the “helper” thread pool

pub fn create_context(&self, id: &str) -> Result<(), EsError>

create a new context besides the always existing main_context

todo

EsRuntime needs some more pub methods using context like eval / call_func

Example

use quickjs_runtime::esruntimebuilder::EsRuntimeBuilder;
use quickjs_runtime::esscript::EsScript;
let rt = EsRuntimeBuilder::new().build();
rt.create_context("my_context");
rt.add_to_event_queue_sync(|q_js_rt| {
   let my_ctx = q_js_rt.get_context("my_context");
   my_ctx.eval(EsScript::new("ctx_test.es", "this.myVar = 'only exists in my_context';"));
});

pub fn drop_context(&self, id: &str)

drop a context which was created earlier with a call to create_context()