Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[DOCS] Adds runtime documentation #862

Merged
merged 1 commit into from
Nov 29, 2018
Merged

[DOCS] Adds runtime documentation #862

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions guides/01-introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion guides/02-precompiler-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
34 changes: 32 additions & 2 deletions guides/03-runtime-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like this is actually describing the compilation step? I.e. "saves an optimized set of bytecodes" is describing the opcode compiler. This frame is also specific to the lazy/runtime compiler mode, and doesn't hold if you're using Glimmer in the eager/bytecode compiler mode.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, my understanding was that this step could only be done on the first render due to it being dynamic in nature, e.g. Glimmer can't tell if a binding {{foo}} is a constant reference or an updatable one until it renders. Once it visits foo the first time, it notices that foo can never update, and essentially scrubs the update opcodes from the next render cycle.

Is that incorrect? I could also just be using unclear terminology here, from my understanding there are multiple levels of compilation and optimization. Would love to dial this in a bit more.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ahhh, I see. You're describing the building of the updating bytecode, but I was interpreting it as describing the just-in-time template compilation of lazy mode. The language here I think could be interpreted to apply to either.

Let's merge this, but revisit if we can make it clearer that this is specifically referring to the partial evaluation optimization.


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

* * *

Expand Down
2 changes: 1 addition & 1 deletion guides/04-references.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion guides/05-validators.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion guides/06-runtime-compiler.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion guides/07-initial-render.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion guides/08-rerendering-updating.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion guides/09-the-environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion guides/10-optimizations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down