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.

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

[DOCS] Adds runtime documentation #862

Merged
merged 1 commit into from
Nov 29, 2018

Conversation

pzuraq
Copy link
Member

@pzuraq pzuraq commented Nov 6, 2018

Been trying to understand the Glimmer VM at a higher level, and how it integrates with Ember and Glimmer.js. I figured it would be good to document my findings as I go through this.

If any of this is incorrect let me know! Still trying to learn and figure out how it all works, both at a high level and a low-level, and would love to get feedback on any parts that could be better 😄

Notes

  • The Glimmer templating languages has diverged a lot from Handlebars, is it still accurate to refer to them as Handlebars templates throughout the docs?
  • Unsure if the Application Lifecycle section should be in the introduction or in the runtime section. Really going for a high level lifecycle, which definitely glosses over large parts of the runtime, but I think is more helpful from the perspective of consumers of Glimmer-VM to understand this lifecycle.
  • I think the Compiler section in the intro should be merged with the precompiler page, seems like it gets too detailed too quickly. Most details mentioned there are implementation details which probably aren't too valuable to consumers of Glimmer-VM (though I may be wrong).

External Sources

Copy link
Contributor

@tomdale tomdale left a comment

Choose a reason for hiding this comment

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

Small nitpick, but other than that I think we should merge as-is as it's certainly an improvement over the status quo.

@@ -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.

@tomdale tomdale changed the title [WIP][DOCS] Adds runtime documentation [DOCS] Adds runtime documentation Nov 29, 2018
@tomdale tomdale merged commit 769a2d9 into glimmerjs:master Nov 29, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants