Struct quickjs_runtime::facades::QuickJsRuntimeFacade

pub struct QuickJsRuntimeFacade { /* private fields */ }

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

Example

use quickjs_runtime::builder::QuickJsRuntimeBuilder;
let rt = QuickJsRuntimeBuilder::new().build();

Implementations

impl QuickJsRuntimeFacade

pub async fn memory_usage(&self) -> MemoryUsage

get memory usage for this runtime

pub fn add_task_to_event_loop_void<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_in_event_loop<C, R: Send + 'static>(&self, task: C) -> R

where C: FnOnce() -> R + Send + 'static,

pub fn add_task_to_event_loop<C, R: Send + 'static>( &self, task: C, ) -> impl Future<Output = R>

where C: FnOnce() -> R + Send + 'static,

pub fn add_rt_task_to_event_loop<C, R: Send + 'static>( &self, task: C, ) -> impl Future<Output = R>

where C: FnOnce(&QuickJsRuntimeAdapter) -> 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::builder::QuickJsRuntimeBuilder;
let rt = QuickJsRuntimeBuilder::new().build();
rt.add_rt_task_to_event_loop(|q_js_rt| {
    // here you are in the worker thread and you can use the quickjs_utils
    q_js_rt.gc();
});

pub fn add_rt_task_to_event_loop_void<C>(&self, task: C)

where C: FnOnce(&QuickJsRuntimeAdapter) + Send + 'static,

pub fn builder() -> QuickJsRuntimeBuilder

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 exe_rt_task_in_event_loop<C, R>(&self, consumer: C) -> R

where C: FnOnce(&QuickJsRuntimeAdapter) -> 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::builder::QuickJsRuntimeBuilder;
use quickjs_runtime::jsutils::Script;
use quickjs_runtime::quickjs_utils::primitives;
let rt = QuickJsRuntimeBuilder::new().build();
let res = rt.exe_rt_task_in_event_loop(|q_js_rt| {
    let q_ctx = q_js_rt.get_main_realm();
    // here you are in the worker thread and you can use the quickjs_utils
    let val_ref = q_ctx.eval(Script::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: &[&str], name: &str, function: F, ) -> Result<(), JsError>

where F: Fn(&QuickJsRealmAdapter, Vec<JsValueFacade>) -> Result<JsValueFacade, JsError> + Send + 'static,

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

Example

use quickjs_runtime::builder::QuickJsRuntimeBuilder;
use quickjs_runtime::quickjs_utils::primitives;
use quickjs_runtime::jsutils::Script;
use quickjs_runtime::values::{JsValueConvertable, JsValueFacade};
  
let rt = QuickJsRuntimeBuilder::new().build();

rt.set_function(&["com", "mycompany", "util"], "methodA", |q_ctx, args: Vec<JsValueFacade>|{
    let a = args[0].get_i32();
    let b = args[1].get_i32();
    Ok((a * b).to_js_value_facade())
}).expect("set func failed");

let res = rt.eval_sync(None, Script::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<(), JsError>

create a new context besides the always existing main_context

Example

use quickjs_runtime::builder::QuickJsRuntimeBuilder;
use quickjs_runtime::jsutils::Script;
let rt = QuickJsRuntimeBuilder::new().build();
rt.create_context("my_context");
rt.exe_rt_task_in_event_loop(|q_js_rt| {
   let my_ctx = q_js_rt.get_context("my_context");
   my_ctx.eval(Script::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()

impl QuickJsRuntimeFacade

pub fn create_realm(&self, name: &str) -> Result<(), JsError>

pub fn destroy_realm(&self, name: &str) -> Result<(), JsError>

pub fn has_realm(&self, name: &str) -> Result<bool, JsError>

pub fn loop_sync<R: Send + 'static, C: FnOnce(&QuickJsRuntimeAdapter) -> R + Send + 'static>( &self, consumer: C, ) -> R

add a job to the eventloop which will execute sync(placed at end of eventloop)

pub fn loop_sync_mut<R: Send + 'static, C: FnOnce(&mut QuickJsRuntimeAdapter) -> R + Send + 'static>( &self, consumer: C, ) -> R

pub fn loop_async<R: Send + 'static, C: FnOnce(&QuickJsRuntimeAdapter) -> R + Send + 'static>( &self, consumer: C, ) -> Pin<Box<dyn Future<Output = R> + Send>>

add a job to the eventloop which will execute async(placed at end of eventloop) returns a Future which can be waited ob with .await

pub fn loop_void<C: FnOnce(&QuickJsRuntimeAdapter) + Send + 'static>( &self, consumer: C, )

add a job to the eventloop (placed at end of eventloop) without expecting a result

pub fn loop_realm_sync<R: Send + 'static, C: FnOnce(&QuickJsRuntimeAdapter, &QuickJsRealmAdapter) -> R + Send + 'static>( &self, realm_name: Option<&str>, consumer: C, ) -> R

add a job to the eventloop which will be executed synchronously (placed at end of eventloop)

pub fn loop_realm<R: Send + 'static, C: FnOnce(&QuickJsRuntimeAdapter, &QuickJsRealmAdapter) -> R + Send + 'static>( &self, realm_name: Option<&str>, consumer: C, ) -> Pin<Box<dyn Future<Output = R>>>

add a job to the eventloop which will be executed async (placed at end of eventloop) returns a Future which can be waited ob with .await

pub fn loop_realm_void<C: FnOnce(&QuickJsRuntimeAdapter, &QuickJsRealmAdapter) + Send + 'static>( &self, realm_name: Option<&str>, consumer: C, )

add a job for a specific realm without expecting a result. the job will be added to the end of the eventloop

pub fn eval( &self, realm_name: Option<&str>, script: Script, ) -> Pin<Box<dyn Future<Output = Result<JsValueFacade, JsError>>>>

Evaluate a script asynchronously

Example

use futures::executor::block_on;
use quickjs_runtime::builder::QuickJsRuntimeBuilder;
use quickjs_runtime::jsutils::Script;
let rt = QuickJsRuntimeBuilder::new().build();
let my_script = r#"
   console.log("i'm a script");
"#;
block_on(rt.eval(None, Script::new("my_script.js", my_script))).expect("script failed");

pub fn eval_sync( &self, realm_name: Option<&str>, script: Script, ) -> Result<JsValueFacade, JsError>

Evaluate a script and return the result synchronously

example

use quickjs_runtime::builder::QuickJsRuntimeBuilder;
use quickjs_runtime::jsutils::Script;
let rt = QuickJsRuntimeBuilder::new().build();
let script = Script::new("my_file.js", "(9 * 3);");
let res = rt.eval_sync(None, script).ok().expect("script failed");
assert_eq!(res.get_i32(), 27);

pub fn eval_module( &self, realm_name: Option<&str>, script: Script, ) -> Pin<Box<dyn Future<Output = Result<JsValueFacade, JsError>>>>

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

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

please note that the module is cached under the absolute path you passed in the Script 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 QuickJsRuntimeFacade with a module loader

example

use futures::executor::block_on;
use quickjs_runtime::builder::QuickJsRuntimeBuilder;
use quickjs_runtime::jsutils::modules::ScriptModuleLoader;
use quickjs_runtime::jsutils::Script;
use quickjs_runtime::quickjsrealmadapter::QuickJsRealmAdapter;
struct TestModuleLoader {}
impl ScriptModuleLoader for TestModuleLoader {
    fn normalize_path(&self, _realm: &QuickJsRealmAdapter, ref_path: &str,path: &str) -> Option<String> {
        Some(path.to_string())
    }

    fn load_module(&self, _realm: &QuickJsRealmAdapter, absolute_path: &str) -> String {
        "export const util = function(a, b, c){return a+b+c;};".to_string()
    }
}
let rt = QuickJsRuntimeBuilder::new().script_module_loader(TestModuleLoader{}).build();
let script = Script::new("/opt/files/my_module.js", r#"
    import {util} from 'other_module.js';\n
    console.log(util(1, 2, 3));
"#);
// in real life you would .await this
let _res = block_on(rt.eval_module(None, script));

pub fn eval_module_sync( &self, realm_name: Option<&str>, script: Script, ) -> Result<JsValueFacade, JsError>

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

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

please note that the module is cached under the absolute path you passed in the Script 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 QuickJsRuntimeFacade with a module loader

example

use quickjs_runtime::builder::QuickJsRuntimeBuilder;
use quickjs_runtime::jsutils::modules::ScriptModuleLoader;
use quickjs_runtime::jsutils::Script;
use quickjs_runtime::quickjsrealmadapter::QuickJsRealmAdapter;
struct TestModuleLoader {}
impl ScriptModuleLoader for TestModuleLoader {
    fn normalize_path(&self, _realm: &QuickJsRealmAdapter, ref_path: &str,path: &str) -> Option<String> {
        Some(path.to_string())
    }

    fn load_module(&self, _realm: &QuickJsRealmAdapter, absolute_path: &str) -> String {
        "export const util = function(a, b, c){return a+b+c;};".to_string()
    }
}
let rt = QuickJsRuntimeBuilder::new().script_module_loader(TestModuleLoader{}).build();
let script = Script::new("/opt/files/my_module.js", r#"
    import {util} from 'other_module.js';\n
    console.log(util(1, 2, 3));
"#);
let _res = rt.eval_module_sync(None, script);

pub fn invoke_function_sync( &self, realm_name: Option<&str>, namespace: &[&str], method_name: &str, args: Vec<JsValueFacade>, ) -> Result<JsValueFacade, JsError>

invoke a function in the engine and get the result synchronously

example

use quickjs_runtime::builder::QuickJsRuntimeBuilder;
use quickjs_runtime::jsutils::Script;
use quickjs_runtime::values::JsValueConvertable;
let rt = QuickJsRuntimeBuilder::new().build();
let script = Script::new("my_file.es", "this.com = {my: {methodA: function(a, b, someStr, someBool){return a*b;}}};");
rt.eval_sync(None, script).ok().expect("script failed");
let res = rt.invoke_function_sync(None, &["com", "my"], "methodA", vec![7i32.to_js_value_facade(), 5i32.to_js_value_facade(), "abc".to_js_value_facade(), true.to_js_value_facade()]).ok().expect("func failed");
assert_eq!(res.get_i32(), 35);

pub fn invoke_function( &self, realm_name: Option<&str>, namespace: &[&str], method_name: &str, args: Vec<JsValueFacade>, ) -> Pin<Box<dyn Future<Output = Result<JsValueFacade, JsError>>>>

invoke 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::builder::QuickJsRuntimeBuilder;
use quickjs_runtime::jsutils::Script;
use quickjs_runtime::values::JsValueConvertable;
let rt = QuickJsRuntimeBuilder::new().build();
let script = Script::new("my_file.es", "this.com = {my: {methodA: function(a, b){return a*b;}}};");
rt.eval_sync(None, script).ok().expect("script failed");
rt.invoke_function(None, &["com", "my"], "methodA", vec![7.to_js_value_facade(), 5.to_js_value_facade()]);

pub fn invoke_function_void( &self, realm_name: Option<&str>, namespace: &[&str], method_name: &str, args: Vec<JsValueFacade>, )

Trait Implementations

impl Drop for QuickJsRuntimeFacade

fn drop(&mut self)

Executes the destructor for this type.