feat: first working version of new allocator
This commit is contained in:
Max Richter
294
SUMMARY_RUNTIME.md
Normal file
294
SUMMARY_RUNTIME.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# Node Compilation and Runtime Execution
|
||||
|
||||
## Overview
|
||||
|
||||
Nodarium nodes are WebAssembly modules written in Rust. Each node is a compiled WASM binary that exposes a standardized C ABI interface. The system uses procedural macros to generate the necessary boilerplate for node definitions, memory management, and execution.
|
||||
|
||||
## Node Compilation
|
||||
|
||||
### 1. Node Definition (JSON)
|
||||
|
||||
Each node has a `src/input.json` file that defines:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "max/plantarium/stem",
|
||||
"meta": { "description": "Creates a stem" },
|
||||
"outputs": ["path"],
|
||||
"inputs": {
|
||||
"origin": { "type": "vec3", "value": [0, 0, 0], "external": true },
|
||||
"amount": { "type": "integer", "value": 1, "min": 1, "max": 64 },
|
||||
"length": { "type": "float", "value": 5 },
|
||||
"thickness": { "type": "float", "value": 0.2 }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Procedural Macros
|
||||
|
||||
The `nodarium_macros` crate provides two procedural macros:
|
||||
|
||||
#### `#[nodarium_execute]`
|
||||
|
||||
Transforms a Rust function into a WASM-compatible entry point:
|
||||
|
||||
```rust
|
||||
#[nodarium_execute]
|
||||
pub fn execute(input: &[i32]) -> Vec<i32> {
|
||||
// Node logic here
|
||||
}
|
||||
```
|
||||
|
||||
The macro generates:
|
||||
- **C ABI wrapper**: Converts the WASM interface to a standard C FFI
|
||||
- **`execute` function**: Takes `(ptr: *const i32, len: usize)` and returns `*mut i32`
|
||||
- **Memory allocation**: `__alloc(len: usize) -> *mut i32` for buffer allocation
|
||||
- **Memory deallocation**: `__free(ptr: *mut i32, len: usize)` for cleanup
|
||||
- **Static output buffer**: `OUTPUT_BUFFER` for returning results
|
||||
- **Panic hook**: Routes panics through `host_log_panic` for debugging
|
||||
- **Internal logic wrapper**: Wraps the original function
|
||||
|
||||
#### `nodarium_definition_file!("path")`
|
||||
|
||||
Embeds the node definition JSON into the WASM binary:
|
||||
|
||||
```rust
|
||||
nodarium_definition_file!("src/input.json");
|
||||
```
|
||||
|
||||
Generates:
|
||||
- **`DEFINITION_DATA`**: Static byte array in `nodarium_definition` section
|
||||
- **`get_definition_ptr()`**: Returns pointer to definition data
|
||||
- **`get_definition_len()`**: Returns length of definition data
|
||||
|
||||
### 3. Build Process
|
||||
|
||||
Nodes are compiled with:
|
||||
```bash
|
||||
cargo build --release --target wasm32-unknown-unknown
|
||||
```
|
||||
|
||||
The resulting `.wasm` files are copied to `app/static/nodes/` for serving.
|
||||
|
||||
## Node Execution Runtime
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ WebWorker Thread │
|
||||
│ ┌─────────────────────────────────────────────────────────┐│
|
||||
│ │ WorkerRuntimeExecutor ││
|
||||
│ │ ┌───────────────────────────────────────────────────┐ ││
|
||||
│ │ │ MemoryRuntimeExecutor ││
|
||||
│ │ │ ┌─────────────────────────────────────────────┐ ││
|
||||
│ │ │ │ Node Registry (WASM + Definitions) ││
|
||||
│ │ │ └─────────────────────────────────────────────┘ ││
|
||||
│ │ │ ┌─────────────────────────────────────────────┐ ││
|
||||
│ │ │ │ Execution Engine (Bottom-Up Evaluation) ││
|
||||
│ │ │ └─────────────────────────────────────────────┘ ││
|
||||
│ │ └───────────────────────────────────────────────────┘ ││
|
||||
│ └─────────────────────────────────────────────────────────┘│
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 1. MemoryRuntimeExecutor
|
||||
|
||||
The core execution engine in `runtime-executor.ts`:
|
||||
|
||||
#### Metadata Collection (`addMetaData`)
|
||||
|
||||
1. Load node definitions from registry
|
||||
2. Build parent/child relationships from graph edges
|
||||
3. Calculate execution depth via reverse BFS from output node
|
||||
|
||||
#### Node Sorting
|
||||
|
||||
Nodes are sorted by depth (highest depth first) for bottom-up execution:
|
||||
|
||||
```
|
||||
Depth 3: n3 n6
|
||||
Depth 2: n2 n4 n5
|
||||
Depth 1: n1
|
||||
Depth 0: Output
|
||||
Execution order: n3, n6, n2, n4, n5, n1, Output
|
||||
```
|
||||
|
||||
#### Input Collection
|
||||
|
||||
For each node, inputs are gathered from:
|
||||
1. **Connected nodes**: Results from parent nodes in the graph
|
||||
2. **Node props**: Values stored directly on the node instance
|
||||
3. **Settings**: Global settings mapped via `setting` property
|
||||
4. **Defaults**: Values from node definition
|
||||
|
||||
#### Input Encoding
|
||||
|
||||
Values are encoded as `Int32Array`:
|
||||
- **Floats**: IEEE 754 bits cast to i32
|
||||
- **Vectors**: `[0, count, v1, v2, v3, 1, 1]` (nested bracket format)
|
||||
- **Booleans**: `0` or `1`
|
||||
- **Integers**: Direct i32 value
|
||||
|
||||
#### Caching
|
||||
|
||||
Results are cached using:
|
||||
```typescript
|
||||
inputHash = `node-${node.id}-${fastHashArrayBuffer(encoded_inputs)}`
|
||||
```
|
||||
|
||||
The cache uses LRU eviction (default size: 50 entries).
|
||||
|
||||
### 2. Execution Flow
|
||||
|
||||
```typescript
|
||||
async execute(graph: Graph, settings) {
|
||||
// 1. Load definitions and build node relationships
|
||||
const [outputNode, nodes] = await this.addMetaData(graph);
|
||||
|
||||
// 2. Sort nodes by depth (bottom-up)
|
||||
const sortedNodes = nodes.sort((a, b) => b.depth - a.depth);
|
||||
|
||||
// 3. Execute each node
|
||||
for (const node of sortedNodes) {
|
||||
const inputs = this.collectInputs(node, settings);
|
||||
const encoded = concatEncodedArrays(inputs);
|
||||
const result = nodeType.execute(encoded);
|
||||
this.results[node.id] = result;
|
||||
}
|
||||
|
||||
// 4. Return output node result
|
||||
return this.results[outputNode.id];
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Worker Isolation
|
||||
|
||||
`WorkerRuntimeExecutor` runs execution in a WebWorker via Comlink:
|
||||
|
||||
```typescript
|
||||
class WorkerRuntimeExecutor implements RuntimeExecutor {
|
||||
private worker = new ComlinkWorker(...);
|
||||
|
||||
async execute(graph, settings) {
|
||||
return this.worker.executeGraph(graph, settings);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The worker backend (`worker-runtime-executor-backend.ts`):
|
||||
- Creates a single `MemoryRuntimeExecutor` instance
|
||||
- Manages caching state
|
||||
- Collects performance metrics
|
||||
|
||||
### 4. Remote Execution (Optional)
|
||||
|
||||
`RemoteRuntimeExecutor` can execute graphs on a remote server:
|
||||
|
||||
```typescript
|
||||
class RemoteRuntimeExecutor implements RuntimeExecutor {
|
||||
async execute(graph, settings) {
|
||||
const res = await fetch(this.url, {
|
||||
method: "POST",
|
||||
body: JSON.stringify({ graph, settings })
|
||||
});
|
||||
return new Int32Array(await res.arrayBuffer());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Data Encoding Format
|
||||
|
||||
### Bracket Notation
|
||||
|
||||
Inputs and outputs use a nested bracket encoding:
|
||||
|
||||
```
|
||||
[0, count, item1, item2, ..., 1, 1]
|
||||
^ ^ items ^ ^
|
||||
| | | |
|
||||
| | | +-- closing bracket
|
||||
| +-- number of items + 1 |
|
||||
+-- opening bracket (0) +-- closing bracket (1)
|
||||
```
|
||||
|
||||
### Example Encodings
|
||||
|
||||
**Float (5.0)**:
|
||||
```typescript
|
||||
encodeFloat(5.0) // → 1084227584 (IEEE 754 bits as i32)
|
||||
```
|
||||
|
||||
**Vec3 ([1, 2, 3])**:
|
||||
```typescript
|
||||
[0, 4, encodeFloat(1), encodeFloat(2), encodeFloat(3), 1, 1]
|
||||
```
|
||||
|
||||
**Nested Math Expression**:
|
||||
```
|
||||
[0, 3, 0, 2, 0, 3, 0, 0, 0, 3, 7549747, 127, 1, 1, ...]
|
||||
```
|
||||
|
||||
### Decoding Utilities
|
||||
|
||||
From `packages/utils/src/tree.rs`:
|
||||
- `split_args()`: Parses nested bracket arrays into segments
|
||||
- `evaluate_float()`: Recursively evaluates and decodes float expressions
|
||||
- `evaluate_int()`: Evaluates integer/math node expressions
|
||||
- `evaluate_vec3()`: Decodes vec3 arrays
|
||||
|
||||
## Geometry Data Format
|
||||
|
||||
### Path Data
|
||||
|
||||
Paths represent procedural plant structures:
|
||||
|
||||
```
|
||||
[0, count, [0, header_size, node_type, depth, x, y, z, w, ...], 1, 1]
|
||||
```
|
||||
|
||||
Each point has 4 values: x, y, z position + thickness (w).
|
||||
|
||||
### Geometry Data
|
||||
|
||||
Meshes use a similar format with vertices and face indices.
|
||||
|
||||
## Performance Tracking
|
||||
|
||||
The runtime collects detailed performance metrics:
|
||||
- `collect-metadata`: Time to build node graph
|
||||
- `collected-inputs`: Time to gather inputs
|
||||
- `encoded-inputs`: Time to encode inputs
|
||||
- `hash-inputs`: Time to compute cache hash
|
||||
- `cache-hit`: 1 if cache hit, 0 if miss
|
||||
- `node/{node_type}`: Time per node execution
|
||||
|
||||
## Caching Strategy
|
||||
|
||||
### MemoryRuntimeCache
|
||||
|
||||
LRU cache implementation:
|
||||
```typescript
|
||||
class MemoryRuntimeCache {
|
||||
private map = new Map<string, unknown>();
|
||||
size: number = 50;
|
||||
|
||||
get(key) { /* move to front */ }
|
||||
set(key, value) { /* evict oldest if at capacity */ }
|
||||
}
|
||||
```
|
||||
|
||||
### IndexDBCache
|
||||
|
||||
For persistence across sessions, the registry uses IndexedDB caching.
|
||||
|
||||
## Summary
|
||||
|
||||
The Nodarium node system works as follows:
|
||||
|
||||
1. **Compilation**: Rust functions are decorated with macros that generate C ABI WASM exports
|
||||
2. **Registration**: Node definitions are embedded in WASM and loaded at runtime
|
||||
3. **Graph Analysis**: Runtime builds node relationships and execution order
|
||||
4. **Bottom-Up Execution**: Nodes execute from leaves to output
|
||||
5. **Caching**: Results are cached per-node-inputs hash for performance
|
||||
6. **Isolation**: Execution runs in a WebWorker to prevent main thread blocking
|
||||
Reference in New Issue
Block a user