Autotracked Rendering

An explanation of the depths of the reactivity system we've been using and refining since Ember Octane (ember-source 3.13+).

Walkthrough: setting a value

Given:

import { tracked } from '@glimmer/tracking';

class ModuleState {
    @tracked count = 0;

    increment() {
        this.count++;
    }
}

const state = new ModuleState();

<template>
    <output>{{ state.count }}</output>
    <button {{on "click" state.increment}}>Increment</button>
</template>

And we

1. observe a render,
2. and then click the button,
   • and then observe the output count update.

How does it work?

There are a few systems at play for autotracking:

• [tags]¹
• [global context]²
• the environment / delegate
• some [glue code]³ that [configures]⁴ the [timing specifics]⁵ of when to [render updates]⁶
• the actual [call to the VM to render]⁷

1. leading up to observing a render

• render

  • call renderMain() from glimmer-vm
    • this creates a VM instance and a TemplateIterator
    • tell the renderer to render
      1. executes the VM
      2. iterates over blocks / defers to _execute
      3. evaluate opcodes
      4. this brings us to the low-level VM
      5. the low-level VM is the actual VirtualMachine which inteprets all our opcodes -- it iterates until there are no more opcodes

• read: count

  • access count, which @tracked's getter defers to trackedData

    • the trackedData is in @glimmer/validator instead of using tags directly.
      • trackedData calls consumeTag when the value is access
      • consumeTag adds the tag to the CURRENT_TRACKER
        • this is so that when any {{ }} regions of a template "detect" a dirty tag, they can individually re-render

  • valueForRef

    • called by many opcode handlers in the VM, in this case: this APPEND_OPCODE
    • track
      • calls beginTrackFrame and the corresponding endTrackFrame()

• render a button with modifier

  • for demonstration purposes, this phase is skipped in this explanation, as this document is more about auto-tracking, and less so about how elements and event listeners get wired up

2. click the button

• increment()

  • read: count

    • reading is part of variable++ behavior

  • set: count

    • we dirty the tag via @tracked's setter

  • scheduleRevalidate() is called by dirtyTag(), which then defers to ember to call these things and interacts with the scheduler (we go back to step 1):

    • env.begin
    • env.rerender
    • read: count
    • env.commit

the output, count is rendered as 1

A minimal renderer

JSBin, here

[!CAUTION] This is heavy in boilerplate, and mostly private API. This 300 line minimal example, should be considered our todo list, as having all this required to render a tiny component is too much.