1 # remote-dom-vm bytecode format description
4 write-only instruction set;
6 variable-width instructions;
8 UTF-8 strings prefixed by 32-bit length.
12 ### u32 (unsigned 32-bit integers)
14 Four bytes in big-endian order.
23 As an example, the bytes \[0x12, 0x34, 0x56, 0x78\] represent the number 0x12345678 (305,419,896₁₀).
29 ├───┴───┴───┴───┼───────────────────
30 │ length: u32 │ ... data
31 └───────────────┴───────────────────
34 A string is represented as its length in UTF-8 code units as a u32,
35 followed by the UTF-8 code points.
37 Although JavaScript strings allow unmatched surrogate code points,
38 this layer only allows legal Unicode,
39 for performance, simplicity and brevity of implementation.
41 As a 32-bit unsigned integer, a string’s length lies in the range ◊`[0, 2³²)`.
42 It is not possible to represent strings greater than 4,294,967,295 UTF-8 code units long.
43 If you feel a pressing need to put strings even one *hundredth* of this size into the DOM, you should rethink things.
47 DOM nodes (regardless of subtype, whether document, element, text or comment) are identified by an unsigned 32-bit integer.
48 NodeId 0 is currently reserved for the document being operated upon.
49 (This may change in the future, to a single VM host supporting working with multiple documents.)
50 Certain instructions (opcodes 0–4) reserve a new NodeId.
51 The client and host agree at compile time which of the following NodeId allocation schemes will be used,
52 so that they can both calculate what the next NodeId will be,
53 so that the VM can be write-only.
55 ## NodeId allocation schemes
59 Each new NodeId is one greater than the previous NodeId,
60 with no reuse of past NodeIds.
62 • Excellent for static or almost-static pages,
63 having the lowest baseline memory usage and highest performance.
65 • Cannot create more than 2\³\² nodes in total.
66 In practice, this is not a serious concern:
67 if you create ten thousand nodes per second,
68 which would suggest you were doing something wildly wrong,
69 it still takes five days to exhaust this.
70 (In practice, the memory usage thing will crash your page long before this.)
72 • Memory usage is likely to be proportional to the number of nodes ever created,
73 so heavily dynamic pages will use more memory than they should.
74 (On the VM host side, it will become a sparse array,
75 and the JavaScript engine will probably optimise it so,
76 leaving memory usage proportional to number of current nodes.
77 But on the client side, this is unlikely to be the case,
78 the node map probably being something like ◊code.rs`Vec<Option<Node>>`,
79 and so it’ll probably be using at least four bytes per node ever allocated.
80 This, incidentally, will cause an out-of-memory crash much earlier,
81 probably by no more than a billion nodes.)
85 NodeIds are reused in most-recently-freed order,
86 and if there are no freed NodeIds remaining then a new NodeId is minted,
87 one higher than the previous highest.
89 (The implementation of this is straightforward,
90 but a prose description cumbersome;
91 look at the code if you want more.
92 It involves leaving tombstones and swapping next NodeIds.)
94 • Somewhat higher baseline memory per node,
95 and probably very slightly lower performance.
97 • Memory usage is proportional to the largest number of nodes that existed at one time.
101 The first byte of an instruction is the opcode.
102 After that, instruction widths vary.
106 • document (NodeId of a Document in JavaScript-land)
109 Allocates a new NodeId, corresponding to an HTMLElement in JavaScript-land.
111 ### 1: CreateSvgElement
113 • document (NodeId of a Document in JavaScript-land)
116 Allocates a new NodeId, corresponding to an SVGElement in JavaScript-land.
118 ### 2: CreateTextNode
120 • document (NodeId of a Document in JavaScript-land)
123 Allocates a new NodeId, corresponding to a Text in JavaScript-land.
127 • document (NodeId of a Document in JavaScript-land)
130 Allocates a new NodeId, corresponding to a Comment in JavaScript-land.
132 ### 4: CreateDocumentFragment
134 • document (NodeId of a Document in JavaScript-land)
136 Allocates a new NodeId, corresponding to a DocumentFragment in JavaScript-land.
140 • node (NodeId of a CharacterData in JavaScript-land, meaning a Text or a Comment)
145 • element (NodeId of an Element in JavaScript-land)
149 ### 7: RemoveAttribute
151 • element (NodeId of an Element in JavaScript-land)
156 • parent (NodeId of an Element in JavaScript-land)
157 • new_child (NodeId, typically of a DocumentFragment, Element, Text or Comment)
161 • parent (NodeId of an Element in JavaScript-land)
162 • reference_child (NodeId, typically of a Element, Text or Comment)
163 • new_child (NodeId, typically of a DocumentFragment, Element, Text or Comment)
167 • node (NodeId of any Node)
171 Current implementations assume correct usage and are not robust against incorrect input.
172 Behaviour in the presence of incorrect input is undefined.
174 Client and VM implementations may coordinate on which instructions to support;
175 for example, on an app that never creates any SVG,
176 the code implementing opcode 1 (CreateSvgElement) may be removed;
177 calling it would then produce undefined behaviour.