neon/
lifecycle.rs

1//! # Environment life cycle APIs
2//!
3//! These APIs map to the life cycle of a specific "Agent" or self-contained
4//! environment. If a Neon module is loaded multiple times (Web Workers, worker
5//! threads), these API will be handle data associated with a specific instance.
6//!
7//! See the [N-API Lifecycle][npai-docs] documentation for more details.
8//!
9//! [napi-docs]: https://nodejs.org/api/n-api.html#n_api_environment_life_cycle_apis
10
11use std::{
12    any::Any,
13    marker::PhantomData,
14    sync::{
15        atomic::{AtomicU32, Ordering},
16        Arc,
17    },
18};
19
20use crate::{
21    context::Context,
22    event::Channel,
23    handle::root::NapiRef,
24    sys::{lifecycle, raw::Env, tsfn::ThreadsafeFunction},
25    types::promise::NodeApiDeferred,
26};
27
28#[derive(Copy, Clone, Debug, Eq, PartialEq)]
29#[repr(transparent)]
30/// Uniquely identifies an instance of the module
31///
32/// _Note_: Since `InstanceData` is created lazily, the order of `id` may not
33/// reflect the order that instances were created.
34pub(crate) struct InstanceId(u32);
35
36impl InstanceId {
37    fn next() -> Self {
38        static NEXT_ID: AtomicU32 = AtomicU32::new(0);
39
40        let next = NEXT_ID.fetch_add(1, Ordering::SeqCst).checked_add(1);
41        match next {
42            Some(id) => Self(id),
43            None => panic!("u32 overflow ocurred in Lifecycle InstanceId"),
44        }
45    }
46}
47
48/// `InstanceData` holds Neon data associated with a particular instance of a
49/// native module. If a module is loaded multiple times (e.g., worker threads), this
50/// data will be unique per instance.
51pub(crate) struct InstanceData {
52    id: InstanceId,
53
54    /// Used to free `Root` in the same JavaScript environment that created it
55    ///
56    /// _Design Note_: An `Arc` ensures the `ThreadsafeFunction` outlives the unloading
57    /// of a module. Since it is unlikely that modules will be re-loaded frequently, this
58    /// could be replaced with a leaked `&'static ThreadsafeFunction<NapiRef>`. However,
59    /// given the cost of FFI, this optimization is omitted until the cost of an
60    /// `Arc` is demonstrated as significant.
61    drop_queue: Arc<ThreadsafeFunction<DropData>>,
62
63    /// Shared `Channel` that is cloned to be returned by the `cx.channel()` method
64    shared_channel: Channel,
65
66    /// Table of user-defined instance-local cells.
67    locals: LocalTable,
68}
69
70#[derive(Default)]
71pub(crate) struct LocalTable {
72    cells: Vec<LocalCell>,
73}
74
75pub(crate) type LocalCellValue = Box<dyn Any + Send + 'static>;
76
77#[derive(Default)]
78pub(crate) enum LocalCell {
79    #[default]
80    /// Uninitialized state.
81    Uninit,
82    /// Intermediate "dirty" state representing the middle of a `get_or_try_init` transaction.
83    Trying,
84    /// Fully initialized state.
85    Init(LocalCellValue),
86}
87
88impl LocalCell {
89    /// Establish the initial state at the beginning of the initialization protocol.
90    /// This method ensures that re-entrant initialization always panics (i.e. when
91    /// an existing `get_or_try_init` is in progress).
92    fn pre_init<F>(&mut self, f: F)
93    where
94        F: FnOnce() -> LocalCell,
95    {
96        match self {
97            LocalCell::Uninit => {
98                *self = f();
99            }
100            LocalCell::Trying => panic!("attempt to reinitialize Local during initialization"),
101            LocalCell::Init(_) => {}
102        }
103    }
104
105    pub(crate) fn get<'cx, 'a, C>(cx: &'a mut C, id: usize) -> Option<&'a mut LocalCellValue>
106    where
107        C: Context<'cx>,
108    {
109        let cell = InstanceData::locals(cx).get(id);
110        match cell {
111            LocalCell::Init(ref mut b) => Some(b),
112            _ => None,
113        }
114    }
115
116    pub(crate) fn get_or_init<'cx, 'a, C, F>(
117        cx: &'a mut C,
118        id: usize,
119        f: F,
120    ) -> &'a mut LocalCellValue
121    where
122        C: Context<'cx>,
123        F: FnOnce() -> LocalCellValue,
124    {
125        InstanceData::locals(cx)
126            .get(id)
127            .pre_init(|| LocalCell::Init(f()));
128
129        LocalCell::get(cx, id).unwrap()
130    }
131
132    pub(crate) fn get_or_try_init<'cx, 'a, C, E, F>(
133        cx: &'a mut C,
134        id: usize,
135        f: F,
136    ) -> Result<&'a mut LocalCellValue, E>
137    where
138        C: Context<'cx>,
139        F: FnOnce(&mut C) -> Result<LocalCellValue, E>,
140    {
141        // Kick off a new transaction and drop it before getting the result.
142        {
143            let mut tx = TryInitTransaction::new(cx, id);
144            tx.run(|cx| f(cx))?;
145        }
146
147        // If we're here, the transaction has succeeded, so get the result.
148        Ok(LocalCell::get(cx, id).unwrap())
149    }
150}
151
152impl LocalTable {
153    pub(crate) fn get(&mut self, index: usize) -> &mut LocalCell {
154        if index >= self.cells.len() {
155            self.cells.resize_with(index + 1, Default::default);
156        }
157        &mut self.cells[index]
158    }
159}
160
161/// An RAII implementation of `LocalCell::get_or_try_init`, which ensures that
162/// the state of a cell is properly managed through all possible control paths.
163/// As soon as the transaction begins, the cell is labelled as being in a dirty
164/// state (`LocalCell::Trying`), so that any additional re-entrant attempts to
165/// initialize the cell will fail fast. The `Drop` implementation ensures that
166/// after the transaction, the cell goes back to a clean state of either
167/// `LocalCell::Uninit` if it fails or `LocalCell::Init` if it succeeds.
168struct TryInitTransaction<'cx, 'a, C: Context<'cx>> {
169    cx: &'a mut C,
170    id: usize,
171    _lifetime: PhantomData<&'cx ()>,
172}
173
174impl<'cx, 'a, C: Context<'cx>> TryInitTransaction<'cx, 'a, C> {
175    fn new(cx: &'a mut C, id: usize) -> Self {
176        let mut tx = Self {
177            cx,
178            id,
179            _lifetime: PhantomData,
180        };
181        tx.cell().pre_init(|| LocalCell::Trying);
182        tx
183    }
184
185    /// _Post-condition:_ If this method returns an `Ok` result, the cell is in the
186    /// `LocalCell::Init` state.
187    fn run<E, F>(&mut self, f: F) -> Result<(), E>
188    where
189        F: FnOnce(&mut C) -> Result<LocalCellValue, E>,
190    {
191        if self.is_trying() {
192            let value = f(self.cx)?;
193            *self.cell() = LocalCell::Init(value);
194        }
195        Ok(())
196    }
197
198    fn cell(&mut self) -> &mut LocalCell {
199        InstanceData::locals(self.cx).get(self.id)
200    }
201
202    #[allow(clippy::wrong_self_convention)]
203    fn is_trying(&mut self) -> bool {
204        matches!(self.cell(), LocalCell::Trying)
205    }
206}
207
208impl<'cx, 'a, C: Context<'cx>> Drop for TryInitTransaction<'cx, 'a, C> {
209    fn drop(&mut self) {
210        if self.is_trying() {
211            *self.cell() = LocalCell::Uninit;
212        }
213    }
214}
215
216/// Wrapper for raw Node-API values to be dropped on the main thread
217pub(crate) enum DropData {
218    Deferred(NodeApiDeferred),
219    Ref(NapiRef),
220}
221
222impl DropData {
223    /// Drop a value on the main thread
224    fn drop(env: Option<Env>, data: Self) {
225        if let Some(env) = env {
226            unsafe {
227                match data {
228                    DropData::Deferred(data) => data.leaked(env),
229                    DropData::Ref(data) => data.unref(env),
230                }
231            }
232        }
233    }
234}
235
236impl InstanceData {
237    /// Return the data associated with this module instance, lazily initializing if
238    /// necessary.
239    ///
240    /// # Safety
241    /// No additional locking (e.g., `Mutex`) is necessary because holding a
242    /// `Context` reference ensures serialized access.
243    pub(crate) fn get<'cx, C: Context<'cx>>(cx: &mut C) -> &mut InstanceData {
244        let env = cx.env().to_raw();
245        let data = unsafe { lifecycle::get_instance_data::<InstanceData>(env).as_mut() };
246
247        if let Some(data) = data {
248            return data;
249        }
250
251        let drop_queue = unsafe {
252            let queue = ThreadsafeFunction::new(env, DropData::drop);
253            queue.unref(env);
254            queue
255        };
256
257        let shared_channel = {
258            let mut channel = Channel::new(cx);
259            channel.unref(cx);
260            channel
261        };
262
263        let data = InstanceData {
264            id: InstanceId::next(),
265            drop_queue: Arc::new(drop_queue),
266            shared_channel,
267            locals: LocalTable::default(),
268        };
269
270        unsafe { &mut *lifecycle::set_instance_data(env, data) }
271    }
272
273    /// Helper to return a reference to the `drop_queue` field of `InstanceData`
274    pub(crate) fn drop_queue<'cx, C: Context<'cx>>(
275        cx: &mut C,
276    ) -> Arc<ThreadsafeFunction<DropData>> {
277        Arc::clone(&InstanceData::get(cx).drop_queue)
278    }
279
280    /// Clones the shared channel and references it since new channels should start
281    /// referenced, but the shared channel is unreferenced.
282    pub(crate) fn channel<'cx, C: Context<'cx>>(cx: &mut C) -> Channel {
283        let mut channel = InstanceData::get(cx).shared_channel.clone();
284        channel.reference(cx);
285        channel
286    }
287
288    /// Unique identifier for this instance of the module
289    pub(crate) fn id<'cx, C: Context<'cx>>(cx: &mut C) -> InstanceId {
290        InstanceData::get(cx).id
291    }
292
293    /// Helper to return a reference to the `locals` field of `InstanceData`.
294    pub(crate) fn locals<'cx, C: Context<'cx>>(cx: &mut C) -> &mut LocalTable {
295        &mut InstanceData::get(cx).locals
296    }
297}
neon/lifecycle.rs

neon/
lifecycle.rs
