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 EsRuntime by using the [EsRuntimeBuilder] 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 eval(&self, script: Script) -> Result<EsValueFacade, JsError>

Evaluate a script asynchronously

pub fn eval_sync(&self, script: Script) -> Result<EsValueFacade, JsError>

Evaluate a script and return the result synchronously

example

use quickjs_runtime::builder::QuickJsRuntimeBuilder;
use hirofa_utils::js_utils::Script;
let rt = QuickJsRuntimeBuilder::new().build();
let script = Script::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, JsError>

call a function in the engine and await the result

example

use quickjs_runtime::builder::QuickJsRuntimeBuilder;
use quickjs_runtime::es_args;
use quickjs_runtime::esvalue::EsValueConvertible;
use quickjs_runtime::esvalue::EsValueFacade;
use hirofa_utils::js_utils::Script;
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(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 async fn call_function(
    &self,
    namespace: Vec<&'static str>,
    func_name: String,
    arguments: Vec<EsValueFacade>
) -> Result<EsValueFacade, JsError>

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::builder::QuickJsRuntimeBuilder;
use quickjs_runtime::esvalue::EsValueConvertible;
use hirofa_utils::js_utils::Script;
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(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: Script)

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 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 EsRuntime with a module loader closure

example

use quickjs_runtime::builder::QuickJsRuntimeBuilder;
use hirofa_utils::js_utils::Script;
use quickjs_runtime::esvalue::EsValueConvertible;
use hirofa_utils::js_utils::modules::ScriptModuleLoader;
use quickjs_runtime::quickjsrealmadapter::QuickJsRealmAdapter;
struct TestModuleLoader {}
impl ScriptModuleLoader<QuickJsRealmAdapter> 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(Box::new(TestModuleLoader{})).build();
let script = Script::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: Script) -> Result<EsValueFacade, JsError>

evaluate a module and return result synchronously

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 hirofa_utils::js_utils::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_context();
    // 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: Vec<&'static str>,
    name: &str,
    function: F
) -> Result<(), JsError> where
    F: Fn(&QuickJsRealmAdapter, Vec<EsValueFacade>) -> Result<EsValueFacade, 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 hirofa_utils::js_utils::Script;
use quickjs_runtime::quickjs_utils::primitives;
use quickjs_runtime::esvalue::{EsValueFacade, EsValueConvertible};
let rt = QuickJsRuntimeBuilder::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(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 hirofa_utils::js_utils::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()

Trait Implementations

impl Drop for QuickJsRuntimeFacade

fn drop(&mut self)

Executes the destructor for this type.

impl JsRuntimeFacade for QuickJsRuntimeFacade

type JsRuntimeAdapterType = QuickJsRuntimeAdapter

type JsRuntimeFacadeInnerType = QuickjsRuntimeFacadeInner

fn js_get_runtime_facade_inner(&self) -> Weak<QuickjsRuntimeFacadeInner>

obtain a Weak reference to the JsRuntimeFacadeInner, this is often used to add jobs to the EventLoop from async tasks

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

create a new JavaScript realm or context

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

remove a JavaScript realm or context

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

check if a realm is present

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

util method to add a job to the EventLoop, usually this is passed to the JsRuntimeFacadeInner.js_loop_sync

fn js_loop_sync_mut<R: Send + 'static, C: FnOnce(&mut Self::JsRuntimeAdapterType) -> R + Send + 'static>(
    &self,
    consumer: C
) -> R

util method to add a job to the EventLoop, usually this is passed to the JsRuntimeFacadeInner.js_loop_sync

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

util method to add a job to the EventLoop, usually this is passed to the JsRuntimeFacadeInner.js_loop_sync

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

util method to add a job to the EventLoop, usually this is passed to the JsRuntimeFacadeInner.js_loop_void

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

util method to add a job to the EventLoop, usually this is passed to the JsRuntimeFacadeInner.js_loop_realm_sync if the realm does not exist it should be initialized, in order to customize its initialization you could add a realm_init_hook to the Builder

fn js_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>>>

util method to add a job to the EventLoop, usually this is passed to the JsRuntimeFacadeInner.js_loop_realm if the realm does not exist it should be initialized, in order to customize its initialization you could add a realm_init_hook to the Builder

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

util method to add a job to the EventLoop, usually this is passed to the JsRuntimeFacadeInner.js_loop_realm_void if the realm does not exist it should be initialized, in order to customize its initialization you could add a realm_init_hook to the Builder

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

evaluate a script, please note that eval should not be used for production code, you should always use modules or functions and invoke them eval will always need to parse script and some engines like StarLight even require a different syntax (return(1); vs (1);) If None is passed as realm_name the main Realm wil be used

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

eval a script, please note that eval should not be used for production code, you should always use modules or functions and invoke them eval will always need to parse script and some engines like StarLight even require a different syntax (return(1); vs (1);) If None is passed as realm_name the main Realm wil be used

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

Invoke a function and block until the function is done If None is passed as realm_name the main Realm wil be used

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

Invoke a function this returns a Future which will fulfill when the function is done If None is passed as realm_name the main Realm wil be used

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

Invoke a function without waiting for a result This method may be used instead of js_function_invoke when you don’t want to block_on the future or can’t .await it If None is passed as realm_name the main Realm wil be used