Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix doc #23

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 7 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 11 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -392,7 +392,7 @@ is of a certain type, like `IsUndefined()`, `IsNull`, `IsNumber` etc.
It also has useful methods to convert to a Local<T>, for example:
```c++
V8_WARN_UNUSED_RESULT MaybeLocal<Number> ToNumber(Local<Context> context) const;
V8_WARN_UNUSED_RESULT MaybeLocal<String> ToNumber(Local<String> context) const;
V8_WARN_UNUSED_RESULT MaybeLocal<String> ToString(Local<Context> context) const;
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

...
```

Expand Down Expand Up @@ -452,9 +452,9 @@ $19 = 0x5
See [handle_test.cc](./test/handle_test.cc) for an example.

### HandleScope
Contains a number of Local/Handle's (think pointers to objects but is managed
by V8) and will take care of deleting the Local/Handles for us. HandleScopes
are stack allocated
Contains a number of local handles (like pointers to objects but are managed
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In v8's source code, they use local handles rather than Local/Handles.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think Local is essentially equivalent to Handle. The difference of them is Local is an outer api and Handle is an inner api.

So we can simplify the doc by omitting the Local.

by V8) and will take care of deleting the local handles for us. HandleScopes
are stack allocated.

When ~HandleScope is called all handles created within that scope are removed
from the stack maintained by the HandleScope which makes objects to which the
Expand Down Expand Up @@ -521,7 +521,7 @@ being created:
```c++
Handle<Struct> str = handle(Struct::cast(result), isolate());
```
This will land in the constructor Handle<T>src/handles/handles-inl.h
This will land in the constructor `Handle<T>` in `src/handles/handles-inl.h`:
```c++
template <typename T>
Handle<T>::Handle(T object, Isolate* isolate): HandleBase(object.ptr(), isolate) {}
Expand Down Expand Up @@ -583,8 +583,8 @@ Local handles are located on the stack and are deleted when the appropriate
destructor is called. If there is a local HandleScope then it will take care
of this when the scope returns. When there are no references left to a handle
it can be garbage collected. This means if a function has a HandleScope and
wants to return a handle/local it will not be available after the function
returns. This is what EscapableHandleScope is for, it enable the value to be
wants to return a local handle it will not be available after the function
returns. This is what EscapableHandleScope is for, it enables the value to be
placed in the enclosing handle scope to allow it to survive. When the enclosing
HandleScope goes out of scope it will be cleaned up.

Expand Down Expand Up @@ -680,10 +680,12 @@ Next, we take a look at what happens when the EscapableHandleScope goes out of
scope. This will call HandleScope::~HandleScope which makes sense as any other
Local handles should be cleaned up.

`Escape` copies the value of its argument into the enclosing scope, deletes alli
`Escape` copies the value of its argument into the enclosing scope, deletes all
its local handles, and then gives back the new handle copy which can safely be
returned.

See [escapable_handlescope_test.cc](./test/escapable_handlescope_test.cc) for an example.

### HeapObject
TODO:

Expand All @@ -706,7 +708,7 @@ So a Local contains a pointer to type T. We can access this pointer using

We can cast from a subtype to a supertype using Local::Cast:
```c++
v8::Local<v8::Number> nr = v8::Local<v8::Number>(v8::Number::New(isolate_, 12));
v8::Local<v8::Number> nr = v8::Number::New(isolate_, 12);
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since v8::Number::New return v8::Local<v8::Number>, we can remove unnecessary type conversion.

v8::Local<v8::Value> val = v8::Local<v8::Value>::Cast(nr);
```
And there is also the
Expand Down
2 changes: 1 addition & 1 deletion test/handlescope_test.cc
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ TEST_F(HandleScopeTest, Create) {
TEST_F(HandleScopeTest, HandleScopeImplementer) {
i::Isolate* i_isolate = asInternal(isolate_);
i::HandleScopeImplementer implementer{i_isolate};
// Context is just a HeapObject so we can construct using the default not
// Context is just a HeapObject, so we can construct using the default not
// args constructor.
i::Context context{};

Expand Down