--- f9723f5a6d0d47c7c30e9ec5bf2406f9b31b6230/js/src/frontend/CompilationStencil.h
+++ 295c82f2073e758f5492b96d73dddbbc697c636b/js/src/frontend/CompilationStencil.h
@@ -1024,16 +1024,18 @@ struct ExtensibleCompilationStencil;
// In XDR decode output case, the span and not-owning pointer fields point
// the internal LifoAlloc and the external XDR buffer.
//
// In BorrowingCompilationStencil usage, span and not-owning pointer fields
// point the ExtensibleCompilationStencil and its LifoAlloc.
//
// The dependent XDR buffer or ExtensibleCompilationStencil must be kept
// alive manually.
+//
+// See SMDOC in Stencil.h for more info.
struct CompilationStencil {
friend struct ExtensibleCompilationStencil;
static constexpr ScriptIndex TopLevelIndex = ScriptIndex(0);
static constexpr size_t LifoAllocChunkSize = 512;
// The lifetime of this CompilationStencil may be managed by stack allocation,
@@ -1234,16 +1236,18 @@ struct CompilationStencil {
};
// The top level struct of stencil specialized for extensible case.
// Used as the temporary storage during compilation, an the compilation output.
//
// All not-owning pointer fields point the internal LifoAlloc.
//
// See CompilationStencil for each field's description.
+//
+// Also see SMDOC in Stencil.h for more info.
struct ExtensibleCompilationStencil {
bool canLazilyParse = false;
using FunctionKey = SourceExtent::FunctionKey;
FunctionKey functionKey = SourceExtent::NullFunctionKey;
// Data pointed by other fields are allocated in this LifoAlloc,
--- 74799e55594a03a45b521e8d84db8a3bd9dbae54/js/src/frontend/Stencil.h
+++ 295c82f2073e758f5492b96d73dddbbc697c636b/js/src/frontend/Stencil.h
@@ -104,28 +104,86 @@ using ParserPositionalFormalParameterIte
// * ParserAtom
// * ScopeStencil
// * RegExpStencil
// * BigIntStencil
// * ObjLiteralStencil
// * StencilModuleMetadata
//
//
-// CompilationStencil
-// ------------------
+// CompilationStencil / ExtensibleCompilationStencil
+// -------------------------------------------------
// Parsing a single JavaScript file may generate a tree of `ScriptStencil` that
-// we then package up into the `CompilationStencil` type. This contains a series
-// of vectors segregated by stencil type for fast processing. Delazifying a
-// function will generate its bytecode but some fields remain unchanged from the
-// initial lazy parse.
-//
-// When we delazify a function that was lazily parsed, we generate a new Stencil
-// at the point too. These delazifications can be merged into the Stencil of
-// the initial parse.
+// we then package up into the `ExtensibleCompilationStencil` type or
+// `CompilationStencil`. They contain a series of vectors/spans segregated by
+// data type for fast processing (a.k.a Data Oriented Design).
+//
+// `ExtensibleCompilationStencil` is mutable type used during parsing, and
+// can be allocated either on stack or heap.
+// `ExtensibleCompilationStencil` holds vectors of stencils.
+//
+// `CompilationStencil` is immutable type used for caching the compilation
+// result, and is allocated on heap with refcount.
+// `CompilationStencil` holds spans of stencils, and it can point either
+// owned data or borrowed data.
+// The borrowed data can be from other `ExtensibleCompilationStencil` or
+// from serialized stencil (XDR) on memory or mmap.
+//
+// Delazifying a function will generate its bytecode but some fields remain
+// unchanged from the initial lazy parse.
+// When we delazify a function that was lazily parsed, we generate a new
+// Stencil at the point too. These delazifications can be merged into the
+// Stencil of the initial parse by using `CompilationStencilMerger`.
+//
+// Conversion from ExtensibleCompilationStencil to CompilationStencil
+// ------------------------------------------------------------------
+// There are multiple ways to convert from `ExtensibleCompilationStencil` to
+// `CompilationStencil`:
+//
+// 1. Temporarily borrow `ExtensibleCompilationStencil` content and call
+// function that takes `CompilationStencil` reference, and keep using the
+// `ExtensibleCompilationStencil` after that:
+//
+// ExtensibleCompilationStencil extensible = ...;
+// {
+// BorrowingCompilationStencil stencil(extensible);
+// // Use `stencil reference.
+// }
+//
+// 2. Take the ownership of an on-heap ExtensibleCompilationStencil. This makes
+// the `CompilationStencil` self-contained and it's useful for caching:
+//
+// UniquePtr<ExtensibleCompilationStencil> extensible = ...;
+// CompilationStencil stencil(std::move(extensible));
+//
+// Conversion from CompilationStencil to ExtensibleCompilationStencil
+// ------------------------------------------------------------------
+// In the same way, there are multiple ways to convert from
+// `CompilationStencil` to `ExtensibleCompilationStencil`:
+//
+// 1. Take the ownership of `CompilationStencil`'s underlying data, Only when
+// stencil owns the data and the refcount is 1:
+//
+// RefPtr<CompilationStencil> stencil = ...;
+// ExtensibleCompilationStencil extensible(...);
+// // NOTE: This is equivalent to cloneFrom below if `stencil` has refcount
+// // more than 2, or it doesn't own the data.
+// extensible.steal(fc, std::move(stencil));
+//
+// 2. Clone the underlying data. This is slow but safe operation:
+//
+// CompilationStencil stencil = ...;
+// ExtensibleCompilationStencil extensible(...);
+// extensible.cloneFrom(fc, stencil);
//
+// 3. Take the ownership back from the `CompilationStencil` which is created by
+// taking the ownership of an on-heap `ExtensibleCompilationStencil`:
+//
+// CompilationStencil stencil = ...;
+// ExtensibleCompilationStencil* extensible = stencil.takeOwnedBorrow();
//
// CompilationGCOutput
// -------------------
// When a Stencil is instantiated the equivalent script objects are allocated on
// the GC heap and their pointers are collected into the `CompilationGCOutput`
// structure. This is only used temporarily during instantiation.
//
//
Files
/js/src/frontend/CompilationStencil.h/js/src/frontend/Stencil.hChangesets
Diffs
/js/src/frontend/CompilationStencil.h/js/src/frontend/Stencil.h