From 52b323e802649715af25b2adde05f9035b3899b4 Mon Sep 17 00:00:00 2001 From: Ry Dahl Date: Thu, 19 Dec 2019 07:34:12 -0500 Subject: [PATCH] Add rustdoc for v8::Local (#81) --- src/local.rs | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/src/local.rs b/src/local.rs index b9d74ba7..da66e136 100644 --- a/src/local.rs +++ b/src/local.rs @@ -4,6 +4,39 @@ use std::ops::Deref; use std::ops::DerefMut; use std::ptr::NonNull; +/// An object reference managed by the v8 garbage collector. +/// +/// All objects returned from v8 have to be tracked by the garbage +/// collector so that it knows that the objects are still alive. Also, +/// because the garbage collector may move objects, it is unsafe to +/// point directly to an object. Instead, all objects are stored in +/// handles which are known by the garbage collector and updated +/// whenever an object moves. Handles should always be passed by value +/// (except in cases like out-parameters) and they should never be +/// allocated on the heap. +/// +/// There are two types of handles: local and persistent handles. +/// +/// Local handles are light-weight and transient and typically used in +/// local operations. They are managed by HandleScopes. That means that a +/// HandleScope must exist on the stack when they are created and that they are +/// only valid inside of the HandleScope active during their creation. +/// For passing a local handle to an outer HandleScope, an EscapableHandleScope +/// and its Escape() method must be used. +/// +/// Persistent handles can be used when storing objects across several +/// independent operations and have to be explicitly deallocated when they're no +/// longer used. +/// +/// It is safe to extract the object stored in the handle by +/// dereferencing the handle (for instance, to extract the *Object from +/// a Local); the value will still be governed by a handle +/// behind the scenes and the same rules apply to these values as to +/// their handles. +/// +/// Note: Local handles in Rusty V8 differ from the V8 C++ API in that they are +/// never empty. In situations where empty handles are needed, use +/// Option. pub struct Local<'sc, T>(NonNull, PhantomData<&'sc ()>); impl<'sc, T> Copy for Local<'sc, T> {}