ee596af250
TBR=mvstanton@chromium.org Change-Id: I1f348a050c321968cb20c783ebe4b55f6beed27c Reviewed-on: https://chromium-review.googlesource.com/530826 Reviewed-by: Jochen Eisinger <jochen@chromium.org> Commit-Queue: Jochen Eisinger <jochen@chromium.org> Cr-Commit-Position: refs/heads/master@{#45841}
70 lines
3.1 KiB
Markdown
70 lines
3.1 KiB
Markdown
# The V8 public C++ API
|
|
|
|
# Overview
|
|
|
|
The V8 public C++ API aims to support four use cases:
|
|
|
|
1. Enable applications that embed V8 (called the embedder) to configure and run
|
|
one or more instances of V8.
|
|
2. Expose ECMAScript-like capabilities to the embedder.
|
|
3. Enable the embedder to interact with ECMAScript by exposing API objects.
|
|
4. Provide access to the V8 debugger (inspector).
|
|
|
|
# Configuring and running an instance of V8
|
|
|
|
V8 requires access to certain OS-level primitives such as the ability to
|
|
schedule work on threads, or allocate memory.
|
|
|
|
The embedder can define how to access those primitives via the v8::Platform
|
|
interface. While V8 bundles a basic implementation, embedders are highly
|
|
encouraged to implement v8::Platform themselves.
|
|
|
|
Currently, the v8::ArrayBuffer::Allocator is passed to the v8::Isolate factory
|
|
method, however, conceptually it should also be part of the v8::Platform since
|
|
all instances of V8 should share one allocator.
|
|
|
|
Once the v8::Platform is configured, an v8::Isolate can be created. All
|
|
further interactions with V8 should explicitly reference the v8::Isolate they
|
|
refer to. All API methods should eventually take an v8::Isolate parameter.
|
|
|
|
When a given instance of V8 is no longer needed, it can be destroyed by
|
|
disposing the respective v8::Isolate. If the embedder wishes to free all memory
|
|
associated with the v8::Isolate, it has to first clear all global handles
|
|
associated with that v8::Isolate.
|
|
|
|
# ECMAScript-like capabilities
|
|
|
|
In general, the C++ API shouldn't enable capabilities that aren't available to
|
|
scripts running in V8. Experience has shown that it's not possible to maintain
|
|
such API methods in the long term. However, capabilities also available to
|
|
scripts, i.e., ones that are defined in the ECMAScript standard are there to
|
|
stay, and we can safely expose them to embedders.
|
|
|
|
The C++ API should also be pleasant to use, and not require learning new
|
|
paradigms. Similarly to how the API exposed to scripts aims to provide good
|
|
ergonomics, we should aim to provide a reasonable developer experience for this
|
|
API surface.
|
|
|
|
ECMAScript makes heavy use of exceptions, however, V8's C++ code doesn't use
|
|
C++ exceptions. Therefore, all API methods that can throw exceptions should
|
|
indicate so by returning a v8::Maybe<> or v8::MaybeLocal<> result,
|
|
and by taking a v8::Local<v8::Context> parameter that indicates in which
|
|
context a possible exception should be thrown.
|
|
|
|
# API objects
|
|
|
|
V8 allows embedders to define special objects that expose additional
|
|
capabilities and APIs to scripts. The most prominent example is exposing the
|
|
HTML DOM in Blink. Other examples are e.g. node.js. It is less clear what kind
|
|
of capabilities we want to expose via this API surface. As a rule of thumb, we
|
|
want to expose operations as defined in the WebIDL and HTML spec: we
|
|
assume that those requirements are somewhat stable, and that they are a
|
|
superset of the requirements of other embedders including node.js.
|
|
|
|
Ideally, the API surfaces defined in those specs hook into the ECMAScript spec
|
|
which in turn guarantees long-term stability of the API.
|
|
|
|
# The V8 inspector
|
|
|
|
All debugging capabilities of V8 should be exposed via the inspector protocol.
|