diff --git a/src/handle_scope.rs b/src/handle_scope.rs index 21b2c88f..a8056faa 100644 --- a/src/handle_scope.rs +++ b/src/handle_scope.rs @@ -32,6 +32,18 @@ extern "C" { ) -> &'sc mut Isolate; } +/// A stack-allocated class that governs a number of local handles. +/// After a handle scope has been created, all local handles will be +/// allocated within that handle scope until either the handle scope is +/// deleted or another handle scope is created. If there is already a +/// handle scope and a new one is created, all allocations will take +/// place in the new handle scope until it is deleted. After that, +/// new handles will again be allocated in the original handle scope. +/// +/// After the handle scope of a local handle has been deleted the +/// garbage collector will no longer track the object stored in the +/// handle and may deallocate it. The behavior of accessing a handle +/// for which the handle scope has been deleted is undefined. #[repr(C)] pub struct HandleScope([usize; 3]); diff --git a/src/module.rs b/src/module.rs index 66b901a6..c886ba80 100644 --- a/src/module.rs +++ b/src/module.rs @@ -75,10 +75,10 @@ pub enum ModuleStatus { Errored, } +/// A compiled JavaScript module. #[repr(C)] pub struct Module(Opaque); -/// A compiled JavaScript module. impl Module { /// Returns the module's current status. pub fn get_status(&self) -> ModuleStatus { diff --git a/src/property.rs b/src/property.rs index 137366d5..67915e03 100644 --- a/src/property.rs +++ b/src/property.rs @@ -6,6 +6,11 @@ use crate::ReturnValue; use std::mem::MaybeUninit; +/// The information passed to a property callback about the context +/// of the property access. +#[repr(C)] +pub struct PropertyCallbackInfo(Opaque); + extern "C" { fn v8__PropertyCallbackInfo__GetIsolate( info: &PropertyCallbackInfo, @@ -18,10 +23,12 @@ extern "C" { ); } -#[repr(C)] -pub struct PropertyCallbackInfo(Opaque); - impl PropertyCallbackInfo { + /// \return The return value of the callback. + /// Can be changed by calling Set(). + /// \code + /// info.GetReturnValue().Set(...) + /// \endcode pub fn get_return_value(&self) -> ReturnValue { let mut rv = MaybeUninit::::uninit(); unsafe { @@ -30,10 +37,50 @@ impl PropertyCallbackInfo { } } + /// The isolate of the property access. pub fn get_isolate(&mut self) -> &mut Isolate { unsafe { v8__PropertyCallbackInfo__GetIsolate(self) } } + /// \return The receiver. In many cases, this is the object on which the + /// property access was intercepted. When using + /// `Reflect.get`, `Function.prototype.call`, or similar functions, it is the + /// object passed in as receiver or thisArg. + /// + /// \code + /// void GetterCallback(Local name, + /// const v8::PropertyCallbackInfo& info) { + /// auto context = info.GetIsolate()->GetCurrentContext(); + /// + /// v8::Local a_this = + /// info.This() + /// ->GetRealNamedProperty(context, v8_str("a")) + /// .ToLocalChecked(); + /// v8::Local a_holder = + /// info.Holder() + /// ->GetRealNamedProperty(context, v8_str("a")) + /// .ToLocalChecked(); + /// + /// CHECK(v8_str("r")->Equals(context, a_this).FromJust()); + /// CHECK(v8_str("obj")->Equals(context, a_holder).FromJust()); + /// + /// info.GetReturnValue().Set(name); + /// } + /// + /// v8::Local templ = + /// v8::FunctionTemplate::New(isolate); + /// templ->InstanceTemplate()->SetHandler( + /// v8::NamedPropertyHandlerConfiguration(GetterCallback)); + /// LocalContext env; + /// env->Global() + /// ->Set(env.local(), v8_str("obj"), templ->GetFunction(env.local()) + /// .ToLocalChecked() + /// ->NewInstance(env.local()) + /// .ToLocalChecked()) + /// .FromJust(); + /// + /// CompileRun("obj.a = 'obj'; var r = {a: 'r'}; Reflect.get(obj, 'x', r)"); + /// \endcode pub fn this(&self) -> Local { unsafe { Local::from_raw(v8__PropertyCallbackInfo__This(self)).unwrap() } }