1# The V8 public C++ API 2 3# Overview 4 5The V8 public C++ API aims to support four use cases: 6 71. Enable applications that embed V8 (called the embedder) to configure and run 8 one or more instances of V8. 92. Expose ECMAScript-like capabilities to the embedder. 103. Enable the embedder to interact with ECMAScript by exposing API objects. 114. Provide access to the V8 debugger (inspector). 12 13# Configuring and running an instance of V8 14 15V8 requires access to certain OS-level primitives such as the ability to 16schedule work on threads, or allocate memory. 17 18The embedder can define how to access those primitives via the v8::Platform 19interface. While V8 bundles a basic implementation, embedders are highly 20encouraged to implement v8::Platform themselves. 21 22Currently, the v8::ArrayBuffer::Allocator is passed to the v8::Isolate factory 23method, however, conceptually it should also be part of the v8::Platform since 24all instances of V8 should share one allocator. 25 26Once the v8::Platform is configured, an v8::Isolate can be created. All 27further interactions with V8 should explicitly reference the v8::Isolate they 28refer to. All API methods should eventually take an v8::Isolate parameter. 29 30When a given instance of V8 is no longer needed, it can be destroyed by 31disposing the respective v8::Isolate. If the embedder wishes to free all memory 32associated with the v8::Isolate, it has to first clear all global handles 33associated with that v8::Isolate. 34 35# ECMAScript-like capabilities 36 37In general, the C++ API shouldn't enable capabilities that aren't available to 38scripts running in V8. Experience has shown that it's not possible to maintain 39such API methods in the long term. However, capabilities also available to 40scripts, i.e., ones that are defined in the ECMAScript standard are there to 41stay, and we can safely expose them to embedders. 42 43The C++ API should also be pleasant to use, and not require learning new 44paradigms. Similarly to how the API exposed to scripts aims to provide good 45ergonomics, we should aim to provide a reasonable developer experience for this 46API surface. 47 48ECMAScript makes heavy use of exceptions, however, V8's C++ code doesn't use 49C++ exceptions. Therefore, all API methods that can throw exceptions should 50indicate so by returning a v8::Maybe<> or v8::MaybeLocal<> result, 51and by taking a v8::Local<v8::Context> parameter that indicates in which 52context a possible exception should be thrown. 53 54# API objects 55 56V8 allows embedders to define special objects that expose additional 57capabilities and APIs to scripts. The most prominent example is exposing the 58HTML DOM in Blink. Other examples are e.g. node.js. It is less clear what kind 59of capabilities we want to expose via this API surface. As a rule of thumb, we 60want to expose operations as defined in the WebIDL and HTML spec: we 61assume that those requirements are somewhat stable, and that they are a 62superset of the requirements of other embedders including node.js. 63 64Ideally, the API surfaces defined in those specs hook into the ECMAScript spec 65which in turn guarantees long-term stability of the API. 66 67# The V8 inspector 68 69All debugging capabilities of V8 should be exposed via the inspector protocol. 70The exception to this are profiling features exposed via v8-profiler.h. 71Changes to the inspector protocol need to ensure backwards compatibility and 72commitment to maintain. 73