Skip to content

Commit

Permalink
doc: update markdown files in src for upcoming linting/formatting
Browse files Browse the repository at this point in the history
PR-URL: #40159
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Richard Lau <rlau@redhat.com>
Reviewed-By: Harshitha K P <harshitha014@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
  • Loading branch information
Trott authored and targos committed Oct 4, 2021
1 parent cea7395 commit 847b451
Show file tree
Hide file tree
Showing 2 changed files with 26 additions and 6 deletions.
24 changes: 22 additions & 2 deletions src/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,7 @@ A number of concepts are involved in putting together Node.js on top of V8 and
libuv. This section aims to explain some of them and how they work together.

<a id="isolate"></a>

### `Isolate`

The `v8::Isolate` class represents a single JavaScript engine instance, in
Expand Down Expand Up @@ -102,6 +103,7 @@ subclasses such as `v8::Number` (which in turn has subclasses like `v8::Int32`),
of `v8::Object`, e.g. `v8::Uint8Array` or `v8::Date`.

<a id="internal-fields"></a>

### Internal fields

V8 provides the ability to store data in so-called “internal fields” inside
Expand All @@ -128,12 +130,14 @@ Typical ways of working with internal fields are:
[`Context`][]s provide the same feature under the name “embedder data”.

<a id="js-handles"></a>

### JavaScript value handles

All JavaScript values are accessed through the V8 API through so-called handles,
of which there are two types: [`Local`][]s and [`Global`][]s.

<a id="local-handles"></a>

#### `Local` handles

A `v8::Local` handle is a temporary pointer to a JavaScript object, where
Expand Down Expand Up @@ -210,6 +214,7 @@ any functions that are called from the event loop and want to run or access
JavaScript code to create `HandleScope`s.

<a id="global-handles"></a>

#### `Global` handles

A `v8::Global` handle (sometimes also referred to by the name of its parent
Expand Down Expand Up @@ -246,6 +251,7 @@ the `v8::Eternal` itself is destroyed at some point. This type of handle
is rarely used.
<a id="context"></a>
### `Context`
JavaScript allows multiple global objects and sets of built-in JavaScript
Expand All @@ -270,6 +276,7 @@ Typical ways of accessing the current `Context` in the Node.js code are:
main context.
<a id="event-loop"></a>
### Event loop
The main abstraction for an event loop inside Node.js is the `uv_loop_t` struct.
Expand All @@ -284,6 +291,7 @@ could restructure Node.js to provide e.g. the ability to run parts of Node.js
inside an event loop separate from the active thread’s event loop.
<a id="environment"></a>
### `Environment`
Node.js instances are represented by the `Environment` class.
Expand Down Expand Up @@ -315,6 +323,7 @@ Typical ways of accessing the current `Environment` in the Node.js code are:
up the current [`Context`][] and then uses that.
<a id="isolate-data"></a>
### `IsolateData`
Every Node.js instance ([`Environment`][]) is associated with one `IsolateData`
Expand Down Expand Up @@ -346,6 +355,7 @@ The platform can be accessed through `isolate_data->platform()` given an
and who passed this to Node.js.
<a id="binding-functions"></a>
### Binding functions
C++ functions exposed to JS follow a specific signature. The following example
Expand Down Expand Up @@ -463,6 +473,7 @@ Which explains that the unregistered external reference is
`node::util::GetHiddenValue` defined in `node_util.cc`.

<a id="per-binding-state"></a>

#### Per-binding state

Some internal bindings, such as the HTTP parser, maintain internal state that
Expand Down Expand Up @@ -519,6 +530,7 @@ of `SnapshotableObject` on how to implement its serialization and
deserialization.
<a id="exception-handling"></a>
### Exception handling
The V8 engine provides multiple features to work with JavaScript exceptions,
Expand Down Expand Up @@ -554,7 +566,7 @@ The most common reasons for this are:
* Calls to functions like `object->Get(...)` or `object->Set(...)` may fail on
most objects, if the `Object.prototype` object has been modified from userland
code that added getters or setters.
* Calls that invoke *any* JavaScript code, including JavaScript code that is
* Calls that invoke _any_ JavaScript code, including JavaScript code that is
provided from Node.js internals or V8 internals, will fail when JavaScript
execution is being terminated. This typically happens inside Workers when
`worker.terminate()` is called, but it can also affect the main thread when
Expand Down Expand Up @@ -661,6 +673,7 @@ and the exception object will not be a meaningful JavaScript value.
`try_catch.ReThrow()` should not be used in this case.

<a id="libuv-handles-and-requests"></a>

### libuv handles and requests

Two central concepts when working with libuv are handles and requests.
Expand All @@ -682,6 +695,7 @@ When a Node.js [`Environment`][] is destroyed, it generally needs to clean up
any resources owned by it, e.g. memory or libuv requests/handles.

<a id="cleanup-hooks"></a>

#### Cleanup hooks

Cleanup hooks are provided that run before the [`Environment`][]
Expand All @@ -690,7 +704,7 @@ is destroyed. They can be added and removed through by using
`env->RemoveCleanupHook(callback, hint);`, where callback takes a `void* hint`
argument.

Inside these cleanup hooks, new asynchronous operations *may* be started on the
Inside these cleanup hooks, new asynchronous operations _may_ be started on the
event loop, although ideally that is avoided as much as possible.

Every [`BaseObject`][] has its own cleanup hook that deletes it. For
Expand Down Expand Up @@ -742,6 +756,7 @@ This can be useful for debugging memory leaks.
The [`memory_tracker.h`][] header file explains how to use this class.

<a id="baseobject"></a>

### `BaseObject`

A frequently recurring situation is that a JavaScript object and a C++ object
Expand Down Expand Up @@ -819,6 +834,7 @@ called. This can be useful when one `BaseObject` fully owns another
`BaseObject`.
<a id="asyncwrap"></a>
### `AsyncWrap`
`AsyncWrap` is a subclass of `BaseObject` that additionally provides tracking
Expand All @@ -837,6 +853,7 @@ See the [`async_hooks` module][] documentation for more information about how
this information is provided to async tracking tools.
<a id="makecallback"></a>
#### `MakeCallback`
The `AsyncWrap` class has a set of methods called `MakeCallback()`, with the
Expand Down Expand Up @@ -876,6 +893,7 @@ void StatWatcher::Callback(uv_fs_poll_t* handle,
See [Callback scopes][] for more information.

<a id="handlewrap"></a>

### `HandleWrap`

`HandleWrap` is a subclass of `AsyncWrap` specifically designed to make working
Expand All @@ -890,6 +908,7 @@ current Node.js [`Environment`][] is destroyed, e.g. when a Worker thread stops.
overview over libuv handles managed by Node.js.

<a id="reqwrap"></a>

### `ReqWrap`

`ReqWrap` is a subclass of `AsyncWrap` specifically designed to make working
Expand All @@ -902,6 +921,7 @@ track of the current count of active libuv requests.
overview over libuv handles managed by Node.js.

<a id="callback-scopes"></a>

### Callback scopes

The public `CallbackScope` and the internally used `InternalCallbackScope`
Expand Down
8 changes: 4 additions & 4 deletions src/crypto/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ throughout the rest of the code.
The rest of the files are structured by their function, as detailed in the
following table:

| File (*.h/*.cc) | Description |
| File (\*.h/\*.cc) | Description |
| -------------------- | ----------- |
| `crypto_aes` | AES Cipher support. |
| `crypto_cipher` | General Encryption/Decryption utilities. |
Expand Down Expand Up @@ -98,7 +98,7 @@ Examples of these being used are pervasive through the `src/crypto` code.

### `ByteSource`

The `ByteSource` class is a helper utility representing a *read-only* byte
The `ByteSource` class is a helper utility representing a _read-only_ byte
array. Instances can either wrap external ("foreign") data sources, such as
an `ArrayBuffer` (`v8::BackingStore`) or allocated data. If allocated data
is used, then the allocation is freed automatically when the `ByteSource` is
Expand All @@ -119,9 +119,9 @@ specific to `src/crypto`. It is used extensively within `src/crypto` to hold
allocated data that is intended to be output in response to various
crypto functions (generated hash values, or ciphertext, for instance).

*Currently, we are working to transition away from using `AllocatedBuffer`
_Currently, we are working to transition away from using `AllocatedBuffer`
to directly using the `v8::BackingStore` API. This will take some time.
New uses of `AllocatedBuffer` should be avoided if possible.*
New uses of `AllocatedBuffer` should be avoided if possible._

### Key objects

Expand Down

0 comments on commit 847b451

Please sign in to comment.