quickjs_runtime/lib.rs
1//! # quickjs_runtime
2//! This crate consists of two main parts:
3//! * thread-safe utils and wrappers
4//! you can call these from any thread, all logic is directed to a single worker-thread(EventLoop) which invokes the quickjs API
5//! * quickjs bindings and utils
6//! these talk to the quickjs API directly and need to run in the same thread as the Runtime
7//!
8//! ## Noteworthy structs
9//!
10//! These are the structs you'll use the most
11//!
12//! | Thread safe (Facades) | Runtime Thread-local (Adapters) |
13//! | --- | --- |
14//! | [QuickJsRuntimeFacade](facades/struct.QuickJsRuntimeFacade.html) the 'starting point' | [QuickJsRuntimeAdapter](quickjsruntimeadapter/struct.QuickJsRuntimeAdapter.html) the wrapper for all things quickjs |
15//! | - | [QuickJsRealmAdapter](quickjsrealmadapter/struct.QuickJsRealmAdapter.html) a realm or context |
16//! | [JsValueFacade](https://hirofa.github.io/utils/hirofa_utils/js_utils/facades/values/enum.JsValueFacade.html) copy of- or reference to a value in the JsRuntimeAdapter | [QuickJsValueAdapter](quickjsvalueadapter/struct.QuickJsValueAdapter.html) reference counting pointer to a Value |
17//!
18//! ## Doing something in the runtime worker thread
19//!
20//! You always start with building a new [QuickjsRuntimeFacade](facades/struct.QuickjsRuntimeFacade.html)
21//!
22//! ```dontrun
23//! use quickjs_runtime::builder::QuickJsRuntimeBuilder;
24//! let rt: JsRuntimeFacade = QuickJsRuntimeBuilder::new().js_build();
25//! ```
26//!
27//! [QuickJsRuntimeFacade](facades/struct.QuickJsRuntimeFacade.html) has plenty public methods you can check out but one of the things you'll need to understand is how to communicate with the [QuickJsRuntimeAdapter](quickjsruntimeadapter/struct.QuickJsRuntimeAdapter.html) and the [QuickJsRealmAdapter](quickjsrealmadapter/struct.QuickJsRealmAdapter.html)
28//! This is done by adding a job to the [EventLoop](https://hirofa.github.io/utils/hirofa_utils/eventloop/struct.EventLoop.html) of the [QuickJsRuntimeFacade](facades/struct.QuickJsRuntimeFacade.html)
29//!
30//! ```dontrun
31//! // with the first Option you may specify which realm to use, None indicates the default or main realm
32//! let res = rt.loop_realm(None, |rt: QuickJsRuntimeAdapter, realm: QuickJsRealmAdapter| {
33//! // this will run in the Worker thread, here we can use the Adapters
34//! // since we passed None as realm the realm adapter will be the "main" realm
35//! return true;
36//! }).await;
37//! ```
38//! All the non-sync functions return a Future so you can .await them from async functions.
39//!
40//! In order to do something and get the result synchronously you can use the sync variant
41//! ```dontrun
42//! use quickjs_runtime::quickjsruntime::QuickJsRuntime;
43//! let res = rt.loop_realm_sync(None, |rt, realm| {
44//! // this will run in the Worker thread, here we can use the quickjs API
45//! return 1;
46//! });
47//! ```
48//!
49//! One last thing you need to know is how to pass values from the js engine out of the worker thread
50//!
51//! This is where the JsValueFacade comes in
52//!
53//! ```dontrun
54//!
55//! // init a simple function
56//! rt.eval(Script::new("init_func.js", "globalThis.myObj = {someMember: {someFunction: function(input){return(input + " > hello rust!");}}};")).await;
57//!
58//! // create an input variable by using one of the constructor methods of the JsValueFacade
59//! let input_facade = JsValueFacade::new_str("hello js!");
60//! // move it into a closure which will run in the worker thread
61//! let res = rt.loop_realm(None, move |rt: JsRuntimeAdapter, realm: JsRealmAdapter| {
62//! // convert the input JsValueFacade to JsValueAdapter
63//! let input_adapter = realm.from_js_value_facade(input_facade)?;
64//! // call myObj.someMember.someFunction();
65//! let result_adapter = realm.invoke_function_by_name(&["myObj", "someMember"], "someFunction", &[input_adapter])?;
66//! // convert adapter to facade again so it may move out of the worker thread
67//! return realm.to_js_value_facade(&result_adapter);
68//! }).await;
69//! assert_eq!(res.get_str(), "hello_js! > hello rust!");
70//! ```
71//!
72//! For more details and examples please explore the packages below
73
74#[macro_use]
75extern crate lazy_static;
76extern crate core;
77
78pub mod builder;
79pub mod facades;
80#[cfg(any(
81 feature = "settimeout",
82 feature = "setinterval",
83 feature = "console",
84 feature = "setimmediate"
85))]
86pub mod features;
87pub mod jsutils;
88pub mod quickjs_utils;
89pub mod quickjsrealmadapter;
90pub mod quickjsruntimeadapter;
91pub mod quickjsvalueadapter;
92pub mod reflection;
93#[cfg(feature = "typescript")]
94pub mod typescript;
95pub mod values;
96
97pub use libquickjs_sys;
98
99#[cfg(test)]
100pub mod tests {
101 use crate::builder::QuickJsRuntimeBuilder;
102 use crate::facades::tests::init_test_rt;
103 use crate::facades::QuickJsRuntimeFacade;
104 use crate::jsutils::jsproxies::JsProxy;
105 use crate::jsutils::{JsError, Script};
106 use crate::quickjsrealmadapter::QuickJsRealmAdapter;
107 use crate::values::{JsValueConvertable, JsValueFacade};
108 use futures::executor::block_on;
109 use std::thread;
110 use std::time::Duration;
111
112 #[test]
113 fn test_examples() {
114 let rt = QuickJsRuntimeBuilder::new().build();
115 let outcome = block_on(run_examples(&rt));
116 if outcome.is_err() {
117 log::error!("an error occured: {}", outcome.err().unwrap());
118 }
119 log::info!("done");
120 }
121
122 #[test]
123 fn test_st() {
124 let rt = init_test_rt();
125
126 let _res = rt
127 .eval_sync(
128 None,
129 Script::new(
130 "t.js",
131 r#"
132
133 async function a(){
134 await b();
135 }
136
137 async function b(){
138 throw Error("poof");
139 }
140
141 a().then(() => {
142 console.log("a done");
143 }).catch(() => {
144 console.log("a error");
145 });
146
147 1
148 "#,
149 ),
150 )
151 .expect("script failed");
152 thread::sleep(Duration::from_secs(1));
153 }
154
155 async fn take_long() -> i32 {
156 std::thread::sleep(Duration::from_millis(500));
157 537
158 }
159
160 async fn run_examples(rt: &QuickJsRuntimeFacade) -> Result<(), JsError> {
161 // ensure console.log calls get outputted
162 //simple_logging::log_to_stderr(LevelFilter::Info);
163
164 // do a simple eval on the main realm
165 let eval_res = rt.eval(None, Script::new("simple_eval.js", "2*7;")).await?;
166 log::info!("simple eval:{}", eval_res.get_i32());
167
168 // invoke a JS method from rust
169
170 let meth_res = rt
171 .invoke_function(None, &["Math"], "round", vec![12.321.to_js_value_facade()])
172 .await?;
173 log::info!("Math.round(12.321) = {}", meth_res.get_i32());
174
175 // add a rust function to js as a callback
176
177 let cb = JsValueFacade::new_callback(|args| {
178 let a = args[0].get_i32();
179 let b = args[1].get_i32();
180 log::info!("rust cb was called with a:{} and b:{}", a, b);
181 Ok(JsValueFacade::Null)
182 });
183 rt.invoke_function(
184 None,
185 &[],
186 "setTimeout",
187 vec![
188 cb,
189 10.to_js_value_facade(),
190 12.to_js_value_facade(),
191 13.to_js_value_facade(),
192 ],
193 )
194 .await?;
195 std::thread::sleep(Duration::from_millis(20));
196 log::info!("rust cb should have been called by now");
197
198 // create simple proxy class with an async function
199 rt.loop_realm_sync(None, |_rt_adapter, realm_adapter| {
200 let proxy = JsProxy::new()
201 .namespace(&["com", "mystuff"])
202 .name("MyProxy")
203 .static_method(
204 "doSomething",
205 |_rt_adapter, realm_adapter: &QuickJsRealmAdapter, _args| {
206 realm_adapter.create_resolving_promise_async(
207 async { Ok(take_long().await) },
208 |realm_adapter, producer_result| {
209 realm_adapter.create_i32(producer_result)
210 },
211 )
212 },
213 );
214 realm_adapter
215 .install_proxy(proxy, true)
216 .expect("could not install proxy");
217 });
218
219 rt.eval(
220 None,
221 Script::new(
222 "testMyProxy.js",
223 "async function a() {\
224 console.log('a called at %s ms', new Date().getTime());\
225 let res = await com.mystuff.MyProxy.doSomething();\
226 console.log('a got result %s at %s ms', res, new Date().getTime());\
227 }; a();",
228 ),
229 )
230 .await?;
231 std::thread::sleep(Duration::from_millis(600));
232 log::info!("a should have been called by now");
233
234 Ok(())
235 }
236}