@@ -1,15 +1,14 @@
1−# `dodrio`
1+# Dodrio
22
3−`dodrio` is an **experimental** virtual DOM library for Rust and WebAssembly. It
4−is a proving ground for a bump allocation-based virtual DOM architecture, that I
5−believe is the best way to take advantage of WebAssembly's strengths in the
6−context of a virtual DOM library.
3+A fast, bump-allocated virtual DOM library for Rust and WebAssembly. Note that
4+Dodrio is still **experimental**.
75
86<!-- START doctoc generated TOC please keep comment here to allow auto update -->
97<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
108
119
1210- [Warning](#warning)
11+- [Examples](#examples)
1312- [Design](#design)
1413 - [Bump Allocation](#bump-allocation)
1514 - [Change List as Stack Machine](#change-list-as-stack-machine)
@@ -19,11 +18,46 @@ context of a virtual DOM library.
1918
2019## Warning
2120
22−I reiterate that `dodrio` is in a very **experimental** state. It has not
23−actually been profiled or tuned for performance yet, so while I think the design
24−should yield a very fast virtual DOM library, `dodrio` is almost certainly not
25−fast right now. Additionally, it is probably riddled with bugs, and is assuredly
26−missing features that are critical for actually building Web applications.
21+I reiterate that Dodrio is in a very **experimental** state. It probably has
22+bugs, and no one is using it in production.
23+
24+## Examples
25+
26+Here is the classic "Hello, World!" example:
27+
28+```rust
29+struct Hello {
30+ who: String,
31+}
32+
33+impl Render for Hello {
34+ fn render<'a, 'bump>(&'a self, bump: &'bump Bump) -> Node<'bump>
35+ where
36+ 'a: 'bump,
37+ {
38+ span(bump)
39+ .children([text("Hello, "), text(&self.who), text("!")])
40+ .finish()
41+ }
42+}
43+```
44+
45+More examples can be found in [the `examples`
46+directory](https://github.com/fitzgen/dodrio/tree/master/examples), including:
47+
48+* [`counter`](https://github.com/fitzgen/dodrio/tree/master/examples/counter):
49+ Incrementing and decrementing a counter.
50+* [`input-form`](https://github.com/fitzgen/dodrio/tree/master/examples/input-form):
51+ Reading an `<input>` and displaying its contents.
52+* [`todomvc`](https://github.com/fitzgen/dodrio/tree/master/examples/todomvc):
53+ An implementation of the infamous TodoMVC application.
54+* [`moire`](https://github.com/fitzgen/dodrio/tree/master/examples/moire): The
55+ WebRender Moiré patterns demo.
56+* [`game-of-life`](https://github.com/fitzgen/dodrio/tree/master/examples/game-of-life):
57+ The Rust and WebAssembly book's Game of Life tutorial rendered with Dodrio
58+ instead of to 2D canvas.
59+* [`js-component`](https://github.com/fitzgen/dodrio/tree/master/examples/js-component):
60+ Defines a rendering component in JavaScript with the `dodrio-js-api` crate.
2761
2862## Design
2963
@@ -33,7 +67,7 @@ Bump allocation is essentially the fastest method of allocating objects. It has
3367constraints, but works particularly well when allocation lifetimes match program
3468phases. And virtual DOMs are very phase oriented.
3569
36−`dodrio` maintains three bump allocation arenas:
70+Dodrio maintains three bump allocation arenas:
3771
38721. The newest, most up-to-date virtual DOM. The virtual DOM nodes themselves and
3973 any temporary containers needed while creating them are allocated into this
@@ -46,12 +80,12 @@ phases. And virtual DOMs are very phase oriented.
4680
4781Rendering happens as follows:
4882
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.
83+1. The application state is rendered into bump allocation arena (1).
84+2. (1) is diffed with (2) and the changes are emitted into (3).
85+3. JavaScript code applies the change list in (3) to the physical DOM.
86+4. (1) and (2) are swapped, double-buffering style, and the new (1) has its bump
87+ allocation pointer reset, as does (3).
88+5. Rinse and repeat.
5589
5690### Change List as Stack Machine
5791
@@ -62,10 +96,6 @@ diffs, a task that is essentially a tree traversal.
6296
6397### Library — Not Framework
6498
65−`dodrio` is just a library. (And did I mention it is experimental?!) It is not a
99+Dodrio is just a library. (And did I mention it is experimental?!) It is not a
66100full-fledged, complete, batteries-included solution for all frontend Web
67−development. And it never intends to become that either. Its highest ambition is
68−to prove that its bump allocation-based design is a good one, and maaaayyyyyybe
69−become a production-grade virtual DOM library that you could plug into a larger
70−application or toolkit eventually. But it will never be a complete,
71−batteries-included framework.
101+development. And it never intends to become that either.