mozjs/
context.rs

1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
3 * You can obtain one at http://mozilla.org/MPL/2.0/. */
4
5use std::ops::Deref;
6use std::ptr::NonNull;
7
8pub use crate::jsapi::JSContext as RawJSContext;
9
10/// A wrapper for [raw JSContext pointers](RawJSContext) that are strongly associated with the [Runtime](crate::rust::Runtime) type.
11///
12/// This type is fundamental for safe SpiderMonkey usage.
13/// Each (SpiderMonkey) function which takes [`&mut JSContext`](JSContext) as argument can trigger GC.
14/// SpiderMonkey functions that takes [`&JSContext`](JSContext) are guaranteed to not trigger GC.
15/// We must not hold any unrooted or borrowed data while calling any functions that can trigger GC.
16/// That can causes panics or UB.
17/// For cases where notion of no GC but no actual context is needed, we have [`&NoGC`](NoGC) token.
18///
19/// ```rust
20/// use std::marker::PhantomData;
21/// use mozjs::context::*;
22///
23/// struct ShouldNotBeHoldAcrossGC<'a>(PhantomData<&'a ()>);
24///
25/// impl<'a> Drop for ShouldNotBeHoldAcrossGC<'a> {
26///     fn drop(&mut self) {}
27/// }
28///
29/// fn something_that_should_not_hold_across_gc<'a>(_no_gc: &'a NoGC) -> ShouldNotBeHoldAcrossGC<'a> {
30///     ShouldNotBeHoldAcrossGC(PhantomData)
31/// }
32///
33/// fn SM_function_that_can_trigger_gc(_cx: *mut RawJSContext) {}
34///
35/// // this lives in mozjs
36/// fn safe_wrapper_to_SM_function_that_can_trigger_gc(cx: &mut JSContext) {
37///     unsafe { SM_function_that_can_trigger_gc(cx.raw_cx()) }
38/// }
39///
40/// fn can_cause_gc(cx: &mut JSContext) {
41///     safe_wrapper_to_SM_function_that_can_trigger_gc(cx);
42///     {
43///         let t = something_that_should_not_hold_across_gc(&cx.no_gc());
44///         // do something with it
45///     } // t get dropped
46///     safe_wrapper_to_SM_function_that_can_trigger_gc(cx); // we can call GC again
47/// }
48/// ```
49///
50/// One cannot call any GC function, while any [`&JSContext`](JSContext) or [`&NoGC`](NoGC) is alive,
51/// because they require such functions accept [`&mut JSContext`](JSContext):
52///
53/// ```compile_fail
54/// use std::marker::PhantomData;
55/// use mozjs::context::*;
56/// use mozjs::jsapi::JSContext as RawJSContext;
57///
58/// struct ShouldNotBeHoldAcrossGC<'a>(PhantomData<&'a ()>);
59///
60/// impl<'a> Drop for ShouldNotBeHoldAcrossGC<'a> {
61///     fn drop(&mut self) {} // make type not trivial, or else compiler can shorten it's lifetime
62/// }
63///
64/// fn something_that_should_not_hold_across_gc<'a>(_no_gc: &'a NoGC) -> ShouldNotBeHoldAcrossGC<'a> {
65///     ShouldNotBeHoldAcrossGC(PhantomData)
66/// }
67///
68/// fn safe_wrapper_to_SM_function_that_can_trigger_gc(_cx: &mut JSContext) {
69/// }
70///
71/// fn can_cause_gc(cx: &mut JSContext) {
72///     safe_wrapper_to_SM_function_that_can_trigger_gc(cx);
73///     let t = something_that_should_not_hold_across_gc(&cx.no_gc());
74///     // this will create compile error, because we cannot hold NoGc across C triggering function.
75///     // more specifically we cannot borrow `JSContext` as mutable because it is also borrowed as immutable (NoGC).
76///     safe_wrapper_to_SM_function_that_can_trigger_gc(cx);
77/// }
78/// ```
79///
80/// ### WIP
81///
82/// This model is still being incrementally introduced, so there are currently some escape hatches.
83pub struct JSContext {
84    pub(crate) ptr: NonNull<RawJSContext>,
85}
86
87impl JSContext {
88    /// Wrap an existing [RawJSContext] pointer.
89    ///
90    /// SAFETY:
91    /// - `cx` must be valid [RawJSContext] object.
92    /// - only one [JSContext] can be alive and it should not outlive [Runtime].
93    /// This in turn means that [JSContext] always needs to be passed down as an argument,
94    /// but for the SpiderMonkey callbacks which provide [RawJSContext] it's safe to construct **one** from provided [RawJSContext].
95    pub unsafe fn from_ptr(cx: NonNull<RawJSContext>) -> JSContext {
96        JSContext { ptr: cx }
97    }
98
99    /// Get the `JSContext` for this thread (thin air). This should be rarely used.
100    ///
101    /// SAFETY:
102    /// - only one [JSContext] can be alive and it should not outlive [Runtime].
103    pub unsafe fn get_from_thread() -> Option<JSContext> {
104        unsafe { crate::rust::Runtime::get().map(|raw_cx| unsafe { JSContext::from_ptr(raw_cx) }) }
105    }
106
107    /// Returns [NoGC] token bounded to this [JSContext].
108    /// No function that accepts `&mut JSContext` (read: triggers GC)
109    /// can be called while this is alive.
110    #[inline]
111    #[must_use]
112    pub fn no_gc<'cx>(&'cx self) -> &'cx NoGC {
113        &NoGC(())
114    }
115
116    /// Obtain [RawJSContext] mutable pointer.
117    ///
118    /// # Safety
119    ///
120    /// No [NoGC] tokens should be constructed while returned pointer is available to user.
121    /// In practices this means that one should use the result
122    /// as direct argument to SpiderMonkey function and not store it in variable.
123    ///
124    /// ```rust
125    /// use mozjs::context::*;
126    /// use mozjs::jsapi::JSContext as RawJSContext;
127    ///
128    /// fn SM_function_that_can_trigger_gc(_cx: *mut RawJSContext) {}
129    ///
130    /// fn can_trigger_gc(cx: &mut JSContext) {
131    ///     unsafe { SM_function_that_can_trigger_gc(cx.raw_cx()) } // returned pointer is immediately used
132    ///     cx.no_gc(); // this is ok because no outstanding raw pointer is alive
133    /// }
134    /// ```
135    pub unsafe fn raw_cx(&mut self) -> *mut RawJSContext {
136        self.ptr.as_ptr()
137    }
138
139    /// Obtain [RawJSContext] mutable pointer, that will not be used for GC.
140    ///
141    /// # Safety
142    ///
143    /// No &mut calls should be done on [JSContext] while returned pointer is available.
144    /// In practices this means that one should use the result
145    /// as direct argument to SpiderMonkey function and not store it in variable.
146    ///
147    /// ```rust
148    /// use mozjs::context::*;
149    /// use mozjs::jsapi::JSContext as RawJSContext;
150    ///
151    /// fn SM_function_that_cannot_trigger_gc(_cx: *mut RawJSContext) {}
152    ///
153    /// fn f(cx: &mut JSContext) {
154    ///     unsafe { SM_function_that_cannot_trigger_gc(cx.raw_cx_no_gc()) } // returned pointer is immediately used
155    /// }
156    /// ```
157    pub unsafe fn raw_cx_no_gc(&self) -> *mut RawJSContext {
158        self.ptr.as_ptr()
159    }
160}
161
162impl Deref for JSContext {
163    type Target = NoGC;
164
165    /// Deref [`&JSContext`](JSContext) into [`&NoGC`](NoGC) so that
166    /// one can pass [`&JSContext`](JSContext) to functions that require [`&NoGC`](NoGC).
167    fn deref<'cx>(&'cx self) -> &'cx Self::Target {
168        self.no_gc()
169    }
170}
171
172/// Token that ensures that no GC can happen while it is alive.
173///
174/// This type is similar to `&JSContext`,
175/// but it is used in cases where no actual context is needed.
176///
177/// For more info and examples see [JSContext].
178pub struct NoGC(()); // zero-sized type that cannot be constructed from outside
mozjs/context.rs

mozjs/
context.rs
