pub struct JsRealm(/* private fields */);
Expand description
A representation of a JavaScript realm tied to a JsRuntime
, that allows
execution in the realm’s context.
A JsRealm
instance is a reference to an already existing realm, which
does not hold ownership of it, so instances can be created and dropped as
needed. As such, calling JsRealm::new
doesn’t create a new realm, and
cloning a JsRealm
only creates a new reference. See
JsRuntime::create_realm
to create new realms instead.
Despite JsRealm
instances being references, multiple instances that
point to the same realm won’t overlap because every operation requires
passing a mutable reference to the v8::Isolate
. Therefore, no operation
on two JsRealm
instances tied to the same isolate can be run at the same
time, regardless of whether they point to the same realm.
Panics
Every method of JsRealm
will panic if you call it with a reference to a
v8::Isolate
other than the one that corresponds to the current context.
In other words, the v8::Isolate
parameter for all the related JsRealm
methods
must be extracted from the pre-existing JsRuntime
.
Example usage with the JsRealm::execute_script
method:
use deno_core::JsRuntime;
use deno_core::RuntimeOptions;
use deno_core::CreateRealmOptions;
let mut runtime = JsRuntime::new(RuntimeOptions::default());
let new_realm = runtime
.create_realm(CreateRealmOptions::default())
.expect("Handle the error properly");
let source_code = "var a = 0; a + 1";
let result = new_realm
.execute_script_static(runtime.v8_isolate(), "<anon>", source_code)
.expect("Handle the error properly");
Lifetime of the realm
As long as the corresponding isolate is alive, a JsRealm
instance will
keep the underlying V8 context alive even if it would have otherwise been
garbage collected.
Implementations§
source§impl JsRealm
impl JsRealm
pub fn num_pending_ops(&self) -> usize
pub fn num_unrefed_ops(&self) -> usize
sourcepub fn handle_scope<'s>(&self, isolate: &'s mut Isolate) -> HandleScope<'s>
pub fn handle_scope<'s>(&self, isolate: &'s mut Isolate) -> HandleScope<'s>
For info on the v8::Isolate
parameter, check JsRealm
.
pub fn context(&self) -> &Global<Context>
sourcepub fn global_object<'s>(&self, isolate: &'s mut Isolate) -> Local<'s, Object>
pub fn global_object<'s>(&self, isolate: &'s mut Isolate) -> Local<'s, Object>
For info on the v8::Isolate
parameter, check JsRealm
.
sourcepub fn execute_script_static(
&self,
isolate: &mut Isolate,
name: &'static str,
source_code: &'static str
) -> Result<Global<Value>, Error>
pub fn execute_script_static( &self, isolate: &mut Isolate, name: &'static str, source_code: &'static str ) -> Result<Global<Value>, Error>
Executes traditional JavaScript code (traditional = not ES modules) in the realm’s context.
For info on the v8::Isolate
parameter, check JsRealm
.
The name
parameter can be a filepath or any other string. E.g.:
- “/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(
&self,
isolate: &mut Isolate,
name: &'static str,
source_code: ModuleCode
) -> Result<Global<Value>, Error>
pub fn execute_script( &self, isolate: &mut Isolate, name: &'static str, source_code: ModuleCode ) -> Result<Global<Value>, Error>
Executes traditional JavaScript code (traditional = not ES modules) in the realm’s context.
For info on the v8::Isolate
parameter, check JsRealm
.
The name
parameter can be a filepath or any other string. E.g.:
- “/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 clear_modules(&mut self)
pub fn clear_modules(&mut self)
Clears all loaded modules May not clear all associated memory and should not be used in production
sourcepub fn get_module_namespace(
&self,
isolate: &mut Isolate,
module_id: ModuleId
) -> Result<Global<Object>, Error>
pub fn get_module_namespace( &self, isolate: &mut Isolate, 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 mod_evaluate(
&self,
isolate: &mut Isolate,
id: ModuleId
) -> Receiver<Result<(), Error>> ⓘ
pub fn mod_evaluate( &self, isolate: &mut Isolate, id: ModuleId ) -> Receiver<Result<(), Error>> ⓘ
Evaluates an already instantiated ES module.
Returns a receiver handle 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(
&self,
isolate: &mut Isolate,
specifier: &ModuleSpecifier,
code: Option<ModuleCode>
) -> Result<ModuleId, Error>
pub async fn load_main_module( &self, isolate: &mut Isolate, 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 JsRealm::mod_evaluate
with returned ModuleId
manually after load is finished.
sourcepub async fn load_side_module(
&self,
isolate: &mut Isolate,
specifier: &ModuleSpecifier,
code: Option<ModuleCode>
) -> Result<ModuleId, Error>
pub async fn load_side_module( &self, isolate: &mut Isolate, 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 JsRealm::mod_evaluate
with returned ModuleId
manually after load is finished.