v8-branded-classes.md

Defining Branded Class Types with V8

I'll use the term branded class to be a class hierarchy with:

• a unique internal tag shared by all instances that reliably distinguishes instances from any other objects
• a common set of internal properties
• a fresh constructor/prototype per realm
• brand compatibility across realms: methods that operate on instances of the branded class work on objects of the same branded class that come other realms

Examples: Date, Array, Promise, DOM classes

Isolates (Continents)

Isolate/Continent: separate running instance of JS engine

• its own runtime system
• its own separate GC
• cannot share JS objects with other isolates
• not thread safe by default but can be locked with the v8::Locker API
• not tied to any particular thread, I think? (therefore can't be implicitly tied to TLS)
• internal primitive for building the script portion of in-process workers, tabs, and cross origin or sandboxed iframes
• separate run loop

Contexts (Realms)

Context/Realm: separate JS object graph with fresh copy of builtin libraries

• separate primordials by default
• produce "wrapper" prototypes for primitive values, even when passed in from other realms
• disconnected from other realms by default
• can share JS objects with other realms
• therefore connectivity is opt-in

Function Templates

FunctionTemplate: API for defining a custom species

• belongs to an isolate/continent
• managed by the GC
• independent of context/realm
• has operations for defining the internal object structure of instances (i.e. their hidden class)
• has operations for defining the set of methods and other properties that should exist on the prototype
• automatically manages the instantiation of the constructor for a given context/realm -- instantiates on demand (ft->GetFunction(context))
• has an object template for the prototype, which is also instantiated on demand for a given context/realm
• has an object template for instances, which is used every time any constructor is used with new or the internal ft->NewInstance() is used

Object Templates

ObjectTemplate: API for defining the structure of families of objects

• helps define the structure of instances by predetermining the default instance properties
• can specify internal properties as well