git.iko.soy/dodrio
on 00a42e3 help sign in
dodrio/README.md
71 lines 3.1 kB history raw
1# `dodrio`
3`dodrio` is an **experimental** virtual DOM library for Rust and WebAssembly. It
4is a proving ground for a bump allocation-based virtual DOM architecture, that I
5believe is the best way to take advantage of WebAssembly's strengths in the
6context of a virtual DOM library.
8<!-- START doctoc generated TOC please keep comment here to allow auto update -->
9<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
12- [Warning](#warning)
13- [Design](#design)
14 - [Bump Allocation](#bump-allocation)
15 - [Change List as Stack Machine](#change-list-as-stack-machine)
16 - [Library — Not Framework](#library--not-framework)
18<!-- END doctoc generated TOC please keep comment here to allow auto update -->
20## Warning
22I reiterate that `dodrio` is in a very **experimental** state. It has not
23actually been profiled or tuned for performance yet, so while I think the design
24should yield a very fast virtual DOM library, `dodrio` is almost certainly not
25fast right now. Additionally, it is probably riddled with bugs, and is assuredly
26missing features that are critical for actually building Web applications.
28## Design
30### Bump Allocation
32Bump allocation is essentially the fastest method of allocating objects. It has
33constraints, but works particularly well when allocation lifetimes match program
34phases. And virtual DOMs are very phase oriented.
36`dodrio` maintains three bump allocation arenas:
381. The newest, most up-to-date virtual DOM. The virtual DOM nodes themselves and
39 any temporary containers needed while creating them are allocated into this
40 arena.
412. The previous virtual DOM. This reflects the current state of the physical
42 DOM.
433. The difference between (1) and (2). This is a sequence of DOM mutation
44 operations — colloquially known as a "change list" — which if applied to
45 the physical DOM, will make the physical DOM match (1).
47Rendering happens as follows:
49* The application state is rendered into bump allocation arena (1).
50* (1) diffed with (2) and the changes are emitted into (3).
51* JavaScript code applies the change list in (3) to the physical DOM.
52* (1) and (2) are swapped, double-buffering style, and the new (1) has its bump
53 allocation pointer reset, as does (3).
54* Rinse and repeat.
56### Change List as Stack Machine
58The change list that represents the difference between how the physical DOM
59currently looks, and our ideal virtual DOM state is encoded in a tiny stack
60machine language. A stack machine works particularly well for applying DOM
61diffs, a task that is essentially a tree traversal.
63### Library — Not Framework
65`dodrio` is just a library. (And did I mention it is experimental?!) It is not a
66full-fledged, complete, batteries-included solution for all frontend Web
67development. And it never intends to become that either. Its highest ambition is
68to prove that its bump allocation-based design is a good one, and maaaayyyyyybe
69become a production-grade virtual DOM library that you could plug into a larger
70application or toolkit eventually. But it will never be a complete,
71batteries-included framework.