foster/denoland-deno
1
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2024-11-24 15:19:26 -05:00
Code Issues Packages 1 Wiki Activity

fix(docs): Documentation improvements related to JsRealm. (#16247)

Browse source
This commit is contained in:
Andreu Botella 2022-10-15 22:44:51 +02:00 committed by GitHub
parent fa22956a86
commit 8a736d7dc7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 23 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
core/runtime.rs
View file

@ -504,6 +504,15 @@ impl JsRuntime {
state.global_realm.clone().unwrap()
}
/// Creates a new realm (V8 context) in this JS execution context,
/// pre-initialized with all of the extensions that were passed in
/// [`RuntimeOptions::extensions`] when the [`JsRuntime`] was constructed.
///
/// If the [`JsRuntime`] was not built from a snapshot (see
/// [`RuntimeOptions::startup_snapshot`]), the JS code for the extensions will
/// be run in the call to this method. In contrast, if there is a snapshot,
/// that will be used instead, and the extensions' initialization will come
/// "for free".
pub fn create_realm(&mut self) -> Result<JsRealm, Error> {
let realm = {
// SAFETY: Having the scope tied to self's lifetime makes it impossible to
@ -2066,10 +2075,17 @@ impl JsRuntime {
/// A representation of a JavaScript realm tied to a [`JsRuntime`], that allows
/// execution in the realm's context.
///
/// A [`JsRealm`] instance does not hold ownership of its corresponding realm,
/// so they can be created and dropped as needed. And since every operation on
/// them requires passing a mutable reference to the [`JsRuntime`], multiple
/// [`JsRealm`] instances won't overlap.
/// 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
///
@ -2078,8 +2094,9 @@ impl JsRuntime {
///
/// # Lifetime of the realm
///
/// A [`JsRealm`] instance will keep the underlying V8 context alive even if it
/// would have otherwise been garbage collected.
/// 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.
#[derive(Clone)]
pub struct JsRealm(v8::Global<v8::Context>);
impl JsRealm {