git.iko.soy/dodrio
on master help sign in
dodrio/README.md
108 lines 4.2 kB history raw
1# Dodrio
3A fast, bump-allocated virtual DOM library for Rust and WebAssembly. Note that
4Dodrio is still **experimental**.
6<!-- START doctoc generated TOC please keep comment here to allow auto update -->
7<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
10- [Warning](#warning)
11- [Examples](#examples)
12- [Design](#design)
13 - [Bump Allocation](#bump-allocation)
14 - [Change List as Stack Machine](#change-list-as-stack-machine)
15 - [Library — Not Framework](#library--not-framework)
17<!-- END doctoc generated TOC please keep comment here to allow auto update -->
19## Warning
21I reiterate that Dodrio is in a very **experimental** state. It probably has
22bugs, and no one is using it in production.
24## Examples
26Here is the classic "Hello, World!" example:
28```rust
29struct Hello {
30 who: String,
33impl Render for Hello {
34 fn render<'a>(&self, cx: &mut RenderContext<a>) -> Node<'a> {
35 let who = bumpalo::format!(in cx.bump, "Hello, {}!", self.who);
36 div(cx)
37 .children([text(who.into_bump_str())])
38 .finish()
39 }
41```
43More examples can be found in [the `examples`
44directory](https://github.com/fitzgen/dodrio/tree/master/examples), including:
46* [`counter`](https://github.com/fitzgen/dodrio/tree/master/examples/counter):
47 Incrementing and decrementing a counter.
48* [`input-form`](https://github.com/fitzgen/dodrio/tree/master/examples/input-form):
49 Reading an `<input>` and displaying its contents.
50* [`todomvc`](https://github.com/fitzgen/dodrio/tree/master/examples/todomvc):
51 An implementation of the infamous TodoMVC application.
52* [`moire`](https://github.com/fitzgen/dodrio/tree/master/examples/moire): The
53 WebRender Moiré patterns demo.
54* [`game-of-life`](https://github.com/fitzgen/dodrio/tree/master/examples/game-of-life):
55 The Rust and WebAssembly book's Game of Life tutorial rendered with Dodrio
56 instead of to 2D canvas.
57* [`js-component`](https://github.com/fitzgen/dodrio/tree/master/examples/js-component):
58 Defines a rendering component in JavaScript with the `dodrio-js-api` crate.
60## Cargo Features
62* `log` &mdash; enable debugging-oriented log messages with the `log` crate's
63 facade. You still have to initialize a logger for the messages to go anywhere,
64 such as [`console_log`](https://github.com/iamcodemaker/console_log).
66* `serde` &mdash; enable `serde::{Serialize, Deserialize}` implementations for
67 `Cached<R>` where `R` is serializable and deserializable.
69## Design
71### Bump Allocation
73Bump allocation is essentially the fastest method of allocating objects. It has
74constraints, but works particularly well when allocation lifetimes match program
75phases. And virtual DOMs are very phase oriented.
77Dodrio maintains three bump allocation arenas:
791. The newest, most up-to-date virtual DOM. The virtual DOM nodes themselves and
80 any temporary containers needed while creating them are allocated into this
81 arena.
822. The previous virtual DOM. This reflects the current state of the physical
83 DOM.
843. The difference between (1) and (2). This is a sequence of DOM mutation
85 operations — colloquially known as a "change list" — which if applied to
86 the physical DOM, will make the physical DOM match (1).
88Rendering happens as follows:
901. The application state is rendered into bump allocation arena (1).
912. (1) is diffed with (2) and the changes are emitted into (3).
923. JavaScript code applies the change list in (3) to the physical DOM.
934. (1) and (2) are swapped, double-buffering style, and the new (1) has its bump
94 allocation pointer reset, as does (3).
955. Rinse and repeat.
97### Change List as Stack Machine
99The change list that represents the difference between how the physical DOM
100currently looks, and our ideal virtual DOM state is encoded in a tiny stack
101machine language. A stack machine works particularly well for applying DOM
102diffs, a task that is essentially a tree traversal.
104### Library — Not Framework
106Dodrio is just a library. (And did I mention it is experimental?!) It is not a
107full-fledged, complete, batteries-included solution for all frontend Web
108development. And it never intends to become that either.