pub struct JsRuntime { /* private fields */ }
Expand description
A single execution context of JavaScript. Corresponds roughly to the “Web Worker” concept in the DOM. The JsRuntime future completes when there is an error or when all pending ops have completed.
Use JsRuntimeForSnapshot
to be able to create a snapshot.
Note: since V8 11.6, all runtimes must have a common parent thread that
initalized the V8 platform. This can be done by calling
JsRuntime::init_platform
explicitly, or it will be done automatically on
the calling thread when the first runtime is created.
Implementations§
source§impl JsRuntime
impl JsRuntime
sourcepub fn init_platform(v8_platform: Option<SharedRef<Platform>>)
pub fn init_platform(v8_platform: Option<SharedRef<Platform>>)
Explicitly initalizes the V8 platform using the passed platform. This should only be called once per process. Further calls will be silently ignored.
sourcepub fn new(options: RuntimeOptions) -> JsRuntime
pub fn new(options: RuntimeOptions) -> JsRuntime
Only constructor, configuration is done through options
.
sourcepub fn op_state_from(isolate: &Isolate) -> Rc<RefCell<OpState>>
pub fn op_state_from(isolate: &Isolate) -> Rc<RefCell<OpState>>
Returns the OpState
associated with the passed Isolate
.
pub fn main_context(&self) -> Global<Context>
pub fn v8_isolate(&mut self) -> &mut OwnedIsolate
pub fn inspector(&mut self) -> Rc<RefCell<JsRuntimeInspector>>
sourcepub fn extensions(&self) -> &Vec<Extension>
pub fn extensions(&self) -> &Vec<Extension>
Returns the extensions that this runtime is using (including internal ones).
pub fn handle_scope(&mut self) -> HandleScope<'_>
pub fn eval<'s, T>( scope: &mut HandleScope<'s>, code: &str ) -> Option<Local<'s, T>>where Local<'s, T>: TryFrom<Local<'s, Value>, Error = DataError>,
sourcepub fn op_state(&mut self) -> Rc<RefCell<OpState>>
pub fn op_state(&mut self) -> Rc<RefCell<OpState>>
Returns the runtime’s op state, which can be used to maintain ops and access resources between op calls.
sourcepub fn execute_script(
&mut self,
name: &'static str,
source_code: ModuleCode
) -> Result<Global<Value>, Error>
pub fn execute_script( &mut self, name: &'static str, source_code: ModuleCode ) -> Result<Global<Value>, Error>
Executes traditional JavaScript code (traditional = not ES modules).
The execution takes place on the current main realm, so it is possible to maintain local JS state and invoke this method multiple times.
name
can be a filepath or any other string, but it is required to be 7-bit ASCII, eg.
- “/some/file/path.js”
- “
” - “[native code]”
The same name
value can be used for multiple executions.
Error
can usually be downcast to JsError
.
sourcepub fn execute_script_static(
&mut self,
name: &'static str,
source_code: &'static str
) -> Result<Global<Value>, Error>
pub fn execute_script_static( &mut self, name: &'static str, source_code: &'static str ) -> Result<Global<Value>, Error>
Executes traditional JavaScript code (traditional = not ES modules).
The execution takes place on the current main realm, so it is possible to maintain local JS state and invoke this method multiple times.
name
can be a filepath or any other string, but it is required to be 7-bit ASCII, eg.
- “/some/file/path.js”
- “
” - “[native code]”
The same name
value can be used for multiple executions.
Error
can usually be downcast to JsError
.
sourcepub async fn call_and_await(
&mut self,
function: &Global<Function>
) -> Result<Global<Value>, Error>
pub async fn call_and_await( &mut self, function: &Global<Function> ) -> Result<Global<Value>, Error>
Call a function. If it returns a promise, run the event loop until that
promise is settled. If the promise rejects or there is an uncaught error
in the event loop, return Err(error)
. Or return Ok(<await returned>)
.
sourcepub async fn call_with_args_and_await(
&mut self,
function: &Global<Function>,
args: &[Global<Value>]
) -> Result<Global<Value>, Error>
pub async fn call_with_args_and_await( &mut self, function: &Global<Function>, args: &[Global<Value>] ) -> Result<Global<Value>, Error>
Call a function with args. If it returns a promise, run the event loop until that
promise is settled. If the promise rejects or there is an uncaught error
in the event loop, return Err(error)
. Or return Ok(<await returned>)
.
sourcepub fn get_module_namespace(
&mut self,
module_id: ModuleId
) -> Result<Global<Object>, Error>
pub fn get_module_namespace( &mut self, module_id: ModuleId ) -> Result<Global<Object>, Error>
Returns the namespace object of a module.
This is only available after module evaluation has completed. This function panics if module has not been instantiated.
sourcepub fn add_near_heap_limit_callback<C>(&mut self, cb: C)where
C: FnMut(usize, usize) -> usize + 'static,
pub fn add_near_heap_limit_callback<C>(&mut self, cb: C)where C: FnMut(usize, usize) -> usize + 'static,
Registers a callback on the isolate when the memory limits are approached. Use this to prevent V8 from crashing the process when reaching the limit.
Calls the closure with the current heap limit and the initial heap limit. The return value of the closure is set as the new limit.
pub fn remove_near_heap_limit_callback(&mut self, heap_limit: usize)
pub fn maybe_init_inspector(&mut self)
pub fn poll_value( &mut self, cx: &mut Context<'_>, global: &Global<Value> ) -> Poll<Result<Global<Value>, Error>>
sourcepub async fn resolve_value(
&mut self,
global: Global<Value>
) -> Result<Global<Value>, Error>
pub async fn resolve_value( &mut self, global: Global<Value> ) -> Result<Global<Value>, Error>
Waits for the given value to resolve while polling the event loop.
This future resolves when either the value is resolved or the event loop runs to completion.
sourcepub async fn run_event_loop(
&mut self,
wait_for_inspector: bool
) -> Result<(), Error>
pub async fn run_event_loop( &mut self, wait_for_inspector: bool ) -> Result<(), Error>
Runs event loop to completion
This future resolves when:
- there are no more pending dynamic imports
- there are no more pending ops
- there are no more active inspector sessions (only if
wait_for_inspector
is set to true)
sourcepub async fn run_event_loop2(
&mut self,
poll_options: PollEventLoopOptions
) -> Result<(), Error>
pub async fn run_event_loop2( &mut self, poll_options: PollEventLoopOptions ) -> Result<(), Error>
Runs event loop to completion
This future resolves when:
- there are no more pending dynamic imports
- there are no more pending ops
- there are no more active inspector sessions (only if
PollEventLoopOptions.wait_for_inspector
is set to true)
sourcepub async fn with_event_loop<'fut, T>(
&mut self,
fut: Pin<Box<dyn Future<Output = T> + 'fut>>,
poll_options: PollEventLoopOptions
) -> T
pub async fn with_event_loop<'fut, T>( &mut self, fut: Pin<Box<dyn Future<Output = T> + 'fut>>, poll_options: PollEventLoopOptions ) -> T
A utility function that run provided future concurrently with the event loop.
Useful for interacting with local inspector session.
sourcepub fn poll_event_loop(
&mut self,
cx: &mut Context<'_>,
wait_for_inspector: bool
) -> Poll<Result<(), Error>>
pub fn poll_event_loop( &mut self, cx: &mut Context<'_>, wait_for_inspector: bool ) -> Poll<Result<(), Error>>
Runs a single tick of event loop
If wait_for_inspector
is set to true event loop
will return Poll::Pending
if there are active inspector sessions.
sourcepub fn poll_event_loop2(
&mut self,
cx: &mut Context<'_>,
poll_options: PollEventLoopOptions
) -> Poll<Result<(), Error>>
pub fn poll_event_loop2( &mut self, cx: &mut Context<'_>, poll_options: PollEventLoopOptions ) -> Poll<Result<(), Error>>
Runs a single tick of event loop
If PollEventLoopOptions.wait_for_inspector
is set to true, the event
loop will return Poll::Pending
if there are active inspector sessions.
source§impl JsRuntime
impl JsRuntime
sourcepub fn mod_evaluate(
&mut self,
id: ModuleId
) -> impl Future<Output = Result<(), Error>>
pub fn mod_evaluate( &mut self, id: ModuleId ) -> impl Future<Output = Result<(), Error>>
Evaluates an already instantiated ES module.
Returns a future that resolves when module promise resolves.
Implementors must manually call JsRuntime::run_event_loop
to drive
module evaluation future.
Error
can usually be downcast to JsError
and should be awaited and
checked after JsRuntime::run_event_loop
completion.
This function panics if module has not been instantiated.
sourcepub async fn load_main_module(
&mut self,
specifier: &ModuleSpecifier,
code: Option<ModuleCode>
) -> Result<ModuleId, Error>
pub async fn load_main_module( &mut self, specifier: &ModuleSpecifier, code: Option<ModuleCode> ) -> Result<ModuleId, Error>
Asynchronously load specified module and all of its dependencies.
The module will be marked as “main”, and because of that “import.meta.main” will return true when checked inside that module.
User must call JsRuntime::mod_evaluate
with returned ModuleId
manually after load is finished.
sourcepub async fn load_side_module(
&mut self,
specifier: &ModuleSpecifier,
code: Option<ModuleCode>
) -> Result<ModuleId, Error>
pub async fn load_side_module( &mut self, specifier: &ModuleSpecifier, code: Option<ModuleCode> ) -> Result<ModuleId, Error>
Asynchronously load specified ES module and all of its dependencies.
This method is meant to be used when loading some utility code that might be later imported by the main module (ie. an entry point module).
User must call JsRuntime::mod_evaluate
with returned ModuleId
manually after load is finished.