Skip to content
A fast, bump-allocated virtual DOM library for Rust and WebAssembly.
Branch: master
Clone or download
fitzgen Fix `ChangeDiscriminant`'s immediates documentation
Most of the instructions use interned strings now.
Latest commit b2db3d5 Mar 23, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
crates/js-api
examples Merge branch 'sierpinski' Mar 18, 2019
js
src Fix `ChangeDiscriminant`'s immediates documentation Mar 22, 2019
tests/web
.gitignore
.travis.yml
Cargo.lock
Cargo.toml Merge branch 'sierpinski' Mar 18, 2019
LICENSE Initial commit Nov 26, 2018
README.md
build.sh
publish.sh

README.md

Dodrio

A fast, bump-allocated virtual DOM library for Rust and WebAssembly. Note that Dodrio is still experimental.

Warning

I reiterate that Dodrio is in a very experimental state. It probably has bugs, and no one is using it in production.

Examples

Here is the classic "Hello, World!" example:

struct Hello {
    who: String,
}

impl Render for Hello {
    fn render<'a, 'bump>(&'a self, bump: &'bump Bump) -> Node<'bump>
    where
        'a: 'bump,
    {
        span(bump)
            .children([text("Hello, "), text(&self.who), text("!")])
            .finish()
    }
}

More examples can be found in the examples directory, including:

  • counter: Incrementing and decrementing a counter.
  • input-form: Reading an <input> and displaying its contents.
  • todomvc: An implementation of the infamous TodoMVC application.
  • moire: The WebRender Moiré patterns demo.
  • game-of-life: The Rust and WebAssembly book's Game of Life tutorial rendered with Dodrio instead of to 2D canvas.
  • js-component: Defines a rendering component in JavaScript with the dodrio-js-api crate.

Design

Bump Allocation

Bump allocation is essentially the fastest method of allocating objects. It has constraints, but works particularly well when allocation lifetimes match program phases. And virtual DOMs are very phase oriented.

Dodrio maintains three bump allocation arenas:

  1. The newest, most up-to-date virtual DOM. The virtual DOM nodes themselves and any temporary containers needed while creating them are allocated into this arena.
  2. The previous virtual DOM. This reflects the current state of the physical DOM.
  3. The difference between (1) and (2). This is a sequence of DOM mutation operations — colloquially known as a "change list" — which if applied to the physical DOM, will make the physical DOM match (1).

Rendering happens as follows:

  1. The application state is rendered into bump allocation arena (1).
  2. (1) is diffed with (2) and the changes are emitted into (3).
  3. JavaScript code applies the change list in (3) to the physical DOM.
  4. (1) and (2) are swapped, double-buffering style, and the new (1) has its bump allocation pointer reset, as does (3).
  5. Rinse and repeat.

Change List as Stack Machine

The change list that represents the difference between how the physical DOM currently looks, and our ideal virtual DOM state is encoded in a tiny stack machine language. A stack machine works particularly well for applying DOM diffs, a task that is essentially a tree traversal.

Library — Not Framework

Dodrio is just a library. (And did I mention it is experimental?!) It is not a full-fledged, complete, batteries-included solution for all frontend Web development. And it never intends to become that either.

You can’t perform that action at this time.