From fb37792f03086b0a1872d8d223cf5f4f1bc20fe4 Mon Sep 17 00:00:00 2001 From: Christopher Garrett Date: Mon, 5 Nov 2018 19:54:36 -0800 Subject: [PATCH] [DOCS] Adds runtime documentation --- guides/01-introduction.md | 20 +++++++++--------- guides/02-precompiler-overview.md | 2 +- guides/03-runtime-overview.md | 34 +++++++++++++++++++++++++++++-- guides/04-references.md | 2 +- guides/05-validators.md | 2 +- guides/06-runtime-compiler.md | 2 +- guides/07-initial-render.md | 2 +- guides/08-rerendering-updating.md | 2 +- guides/09-the-environment.md | 2 +- guides/10-optimizations.md | 2 +- 10 files changed, 50 insertions(+), 20 deletions(-) diff --git a/guides/01-introduction.md b/guides/01-introduction.md index a179663df..84738f384 100644 --- a/guides/01-introduction.md +++ b/guides/01-introduction.md @@ -2,7 +2,7 @@ 1. [Introduction](./01-introduction.md) 2. [Precompiler Overview](./02-precompiler-overview.md) -3. [~~Runtime Overview~~](./03-runtime-overview.md) +3. [Runtime Overview](./03-runtime-overview.md) 4. [References](./04-references.md) 5. [Validators](./05-validators.md) 6. [~~Runtime Compiler~~](./06-runtime-compiler.md) @@ -14,8 +14,8 @@ # Introduction Glimmer is a flexible, low-level rendering pipeline for building a "live" DOM -from [Handlebars][handlebars] templates that can subsequently be updated cheaply -when data changes. +from a superset of the [Handlebars][handlebars] templating language that can +subsequently be updated cheaply when data changes. In addition to the basic Handlebars features such as helpers and partials, Glimmer also comes with built-in support for a very flexible and powerful @@ -36,11 +36,11 @@ The code examples in this document are written in [TypeScript][typescript]. ## Architecture -The key insight of Glimmer is that Handlebars is a declarative programming -language for building and updating DOM. By structuring web UI around Handlebars -templates as the central abstraction, we can use advanced techniques from -programming languages and compilers to significantly boost the performance of -web applications in practice. +The key insight of Glimmer is that templates represent a declarative programming +language for building and updating DOM. By structuring web UI around templates +as the central abstraction, we can use advanced techniques from programming +languages and compilers to significantly boost the performance of web +applications in practice. Because of this, Glimmer's architecture has more in common with compiler toolchains like clang/LLVM or javac/JVM than traditional JavaScript libraries. @@ -53,8 +53,8 @@ At a high level, Glimmer is made up of two parts: ### Compiler -The compiler is responsible for turning your program's Handlebars templates into -Glimmer binary bytecode. +The compiler is responsible for turning your program's templates into Glimmer +binary bytecode. Because Glimmer is an optimizing compiler, it must know about all of the templates in a program in order to understand how they work together. This is in diff --git a/guides/02-precompiler-overview.md b/guides/02-precompiler-overview.md index 1b47fe4fc..603dd76d2 100644 --- a/guides/02-precompiler-overview.md +++ b/guides/02-precompiler-overview.md @@ -2,7 +2,7 @@ 1. [Introduction](./01-introduction.md) 2. [Precompiler Overview](./02-precompiler-overview.md) -3. [~~Runtime Overview~~](./03-runtime-overview.md) +3. [Runtime Overview](./03-runtime-overview.md) 4. [References](./04-references.md) 5. [Validators](./05-validators.md) 6. [~~Runtime Compiler~~](./06-runtime-compiler.md) diff --git a/guides/03-runtime-overview.md b/guides/03-runtime-overview.md index 47a827ae8..5b73ff6e7 100644 --- a/guides/03-runtime-overview.md +++ b/guides/03-runtime-overview.md @@ -2,7 +2,7 @@ 1. [Introduction](./01-introduction.md) 2. [Precompiler Overview](./02-precompiler-overview.md) -3. [~~Runtime Overview~~](./03-runtime-overview.md) +3. [Runtime Overview](./03-runtime-overview.md) 4. [References](./04-references.md) 5. [Validators](./05-validators.md) 6. [~~Runtime Compiler~~](./06-runtime-compiler.md) @@ -13,7 +13,37 @@ # Runtime Overview -TODO: add content here +The Glimmer runtime takes the compiled bytecode discussed in the previous section and renders it in the browser. At a high level, the runtime begins by rendering a component tree, beginning with one root component and walking down through its templates. While doing this, it saves an optimized set of bytecodes which can be used later on when rerendering the application. These update codes ignore content which is purely static, such as DOM elements and helpers or components which have static inputs, and adds updating instructions for dynamic content. + +Glimmer simultaneously sets up a tree of _references_ and _validators_ for components, helpers, and values. These allow Glimmer to efficiently check if the state of a given subtree of the component hierarchy has changed, and rerender it if so. + +## Application Lifecycle + +At a high level, the runtime centers around around 3 main concepts: + +1. [Components](#component-glossary) +2. [References](#reference-guide) +3. [Validators](#validator-guide) + +**Components** as seen by Glimmer are a reusable unit of UI that encapsulates behavior and appearance. Because Glimmer VM is a highly configurable runtime, the exact meaning of "component" is determined by the host [environment](#environment) and one or more [component managers](#component-manager). + +**References** are stable objects that represents the result of a pure (side-effect-free) computation, where the result of the computation might change over time. Glimmer creates references to represent values used in templates so that they can be efficiently shared across multiple components and efficiently updated should the underlying value change. + +**Validators** are stable objects that provides certain guarantees about the freshness of a computation result. Validators can be combined, such that if any of a child validator's values have been changed, the parent will also be marked as changed. + +A Glimmer application consists of a tree of components, starting with one root component, and evaluating and rendering any references to values, helpers, and other components it may have in its template. You can think of this as the `main` component, similar to the `main` function in many programming languages. Unlike those languages however, the Glimmer VM is fairly low level and doesn't provide a convention for defining this component. This allows host environments to define their conventions and `main` component as they see fit, and render it using Glimmer's `renderMain` function. + +As it renders, Glimmer adds validators for every component and reference it creates. These validators are combined, such that the validator for a given component represents the union of the validators for any references or components it contains, resulting in a tree of validators that matches the component tree. + +Host environments can then provide different methods for invalidating state (via the validators), such as Ember's `set()` function or `@tracked` from Glimmer.js. When rerendering, Glimmer traverses the tree of components, checking each component's validator to see if it needs to be rerendered. If so, it traverses the component's subtree, but if not, the component is skipped entirely. This results in very efficient rerenders as only the portions that have changed will be rerendered by default. + +[component-glossary]: ./11-glossary.md#component +[reference-guide]: ./04-references.md +[validator-guide]: ./05-validators.md + +## The Virtual Machine + +TODO * * * diff --git a/guides/04-references.md b/guides/04-references.md index 8c4476923..e6d7c2558 100644 --- a/guides/04-references.md +++ b/guides/04-references.md @@ -2,7 +2,7 @@ 1. [Introduction](./01-introduction.md) 2. [Precompiler Overview](./02-precompiler-overview.md) -3. [~~Runtime Overview~~](./03-runtime-overview.md) +3. [Runtime Overview](./03-runtime-overview.md) 4. [References](./04-references.md) 5. [Validators](./05-validators.md) 6. [~~Runtime Compiler~~](./06-runtime-compiler.md) diff --git a/guides/05-validators.md b/guides/05-validators.md index b1148de7b..500288352 100644 --- a/guides/05-validators.md +++ b/guides/05-validators.md @@ -2,7 +2,7 @@ 1. [Introduction](./01-introduction.md) 2. [Precompiler Overview](./02-precompiler-overview.md) -3. [~~Runtime Overview~~](./03-runtime-overview.md) +3. [Runtime Overview](./03-runtime-overview.md) 4. [References](./04-references.md) 5. [Validators](./05-validators.md) 6. [~~Runtime Compiler~~](./06-runtime-compiler.md) diff --git a/guides/06-runtime-compiler.md b/guides/06-runtime-compiler.md index 6388755d2..658e3d5a2 100644 --- a/guides/06-runtime-compiler.md +++ b/guides/06-runtime-compiler.md @@ -2,7 +2,7 @@ 1. [Introduction](./01-introduction.md) 2. [Precompiler Overview](./02-precompiler-overview.md) -3. [~~Runtime Overview~~](./03-runtime-overview.md) +3. [Runtime Overview](./03-runtime-overview.md) 4. [References](./04-references.md) 5. [Validators](./05-validators.md) 6. [~~Runtime Compiler~~](./06-runtime-compiler.md) diff --git a/guides/07-initial-render.md b/guides/07-initial-render.md index fd75093aa..6d5c79b5b 100644 --- a/guides/07-initial-render.md +++ b/guides/07-initial-render.md @@ -2,7 +2,7 @@ 1. [Introduction](./01-introduction.md) 2. [Precompiler Overview](./02-precompiler-overview.md) -3. [~~Runtime Overview~~](./03-runtime-overview.md) +3. [Runtime Overview](./03-runtime-overview.md) 4. [References](./04-references.md) 5. [Validators](./05-validators.md) 6. [~~Runtime Compiler~~](./06-runtime-compiler.md) diff --git a/guides/08-rerendering-updating.md b/guides/08-rerendering-updating.md index 772a28d3e..81674893a 100644 --- a/guides/08-rerendering-updating.md +++ b/guides/08-rerendering-updating.md @@ -2,7 +2,7 @@ 1. [Introduction](./01-introduction.md) 2. [Precompiler Overview](./02-precompiler-overview.md) -3. [~~Runtime Overview~~](./03-runtime-overview.md) +3. [Runtime Overview](./03-runtime-overview.md) 4. [References](./04-references.md) 5. [Validators](./05-validators.md) 6. [~~Runtime Compiler~~](./06-runtime-compiler.md) diff --git a/guides/09-the-environment.md b/guides/09-the-environment.md index d92c068b2..8968448b8 100644 --- a/guides/09-the-environment.md +++ b/guides/09-the-environment.md @@ -2,7 +2,7 @@ 1. [Introduction](./01-introduction.md) 2. [Precompiler Overview](./02-precompiler-overview.md) -3. [~~Runtime Overview~~](./03-runtime-overview.md) +3. [Runtime Overview](./03-runtime-overview.md) 4. [References](./04-references.md) 5. [Validators](./05-validators.md) 6. [~~Runtime Compiler~~](./06-runtime-compiler.md) diff --git a/guides/10-optimizations.md b/guides/10-optimizations.md index 887f3e0dd..f76a30606 100644 --- a/guides/10-optimizations.md +++ b/guides/10-optimizations.md @@ -2,7 +2,7 @@ 1. [Introduction](./01-introduction.md) 2. [Precompiler Overview](./02-precompiler-overview.md) -3. [~~Runtime Overview~~](./03-runtime-overview.md) +3. [Runtime Overview](./03-runtime-overview.md) 4. [References](./04-references.md) 5. [Validators](./05-validators.md) 6. [~~Runtime Compiler~~](./06-runtime-compiler.md)