Start a document about the V8 C++ API design

R=mvstanton@chromium.org

Cq-Include-Trybots: master.tryserver.chromium.linux:linux_chromium_rel_ng
Change-Id: Ib45a1d12f2ef869d8b07754d234ff0eedd542188
Reviewed-on: https://chromium-review.googlesource.com/517495
Commit-Queue: Jochen Eisinger <jochen@chromium.org>
Reviewed-by: Michael Stanton <mvstanton@chromium.org>
Reviewed-by: Michael Achenbach <machenbach@chromium.org>
Cr-Commit-Position: refs/heads/master@{#45622}

include/APIDesign.md

+# 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.