dioxus/notes/architecture/07-HOTRELOAD.md

Hot-Reload and Hot-Patching Architecture

Dioxus supports two complementary hot-reload systems: RSX template hot-reload for UI changes, and Subsecond hot-patching for Rust code changes.

Subsecond Hot-Patching

Jump Table Architecture

Subsecond implements hot-patching through jump table indirection:

1. All hot-reloadable functions called through subsecond::call() or HotFn::current()
2. Runtime looks up function pointer in global APP_JUMP_TABLE
3. Jump table points to latest compiled version
4. When patch applied, only jump table is updated
5. Original executable remains untouched

Advantage: Decouples running binary from patched code. Safe memory model.

Patch Application Flow

1. ThinLink compiles only modified functions → patch dylib
2. Patch sent via devtools WebSocket
3. subsecond::apply_patch() loads via libloading::Library
4. Base address calculated using main as anchor
5. Jump table updated with old→new address mappings

ASLR Handling

Operating systems randomize memory addresses (ASLR), so compiled addresses don't match runtime.

Solution:

1. Running app captures real address of main via dlsym()/GetProcAddress()
2. ASLR reference sent to devserver
3. Devserver computes offset: old_offset = aslr_reference - table.aslr_reference
4. All jump table addresses adjusted by offset
5. Patch library base address calculated similarly
6. Final: (old_address + old_offset) → (new_address + new_offset)

Thread-Local Storage (TLS)

TLS presents challenges for hot-patching:

• Globals and statics: Generally supported
• Thread-locals in tip crate: Reset to initial value on new patches
• Thread-locals in dependencies: Work correctly (not re-patched)

Why: New thread-local variables exist in patch library's TLS segment, separate from main executable's TLS. Subsecond doesn't rebind TLS accesses.

Limitations

1. Struct changes: Not supported - size/alignment changes cause crashes
2. Pointer versioning: Not implemented - all function pointers considered "new"
3. Workspace support: Only tip crate patches, library crates ignored
4. Static initializers: Changes not observed
5. Global destructors: Newly added globals have destructors that never run

Platform Support

• Desktop: Linux, macOS, Windows (x86_64, aarch64)
• Mobile: Android (arm64-v8a, armeabi-v7a), iOS Simulator
• Web: WASM32 (limited module reloading)
• Not supported: iOS device (code-signing)

RSX Hot Reload

Hot Literal System

RSX hot reload is orthogonal to subsecond. While subsecond reloads Rust functions, RSX hot reload handles template literal values:

Hot-reloadable:

• Formatted segments: "{variable}"
• Literal component properties: Component { value: 123 }
• Dynamic text nodes: "{expression}"

Not hot-reloadable:

• Rust code changes
• Component structure changes
• Control flow changes

Template Diffing Algorithm

Conservative approach: If Rust code changes, not hot-reloadable.

1. Parse old and new files
2. Extract all rsx! macro invocations
3. Replace all rsx! bodies with empty rsx! {}
4. Remove doc comments
5. Compare modified files
6. If identical → Rust unchanged → proceed with template diff
7. If different → requires full rebuild

Dynamic Pool System

Three pools of reusable items from last build:

1. Dynamic text segments: "{class}", "{id}"
2. Dynamic nodes: Components, for loops, if chains
3. Dynamic attributes: Spread operators, dynamic values

Each item tracks usage with Cell<bool> for waste scoring.

Greedy Matching Algorithm

For each new dynamic node:

1. Find all candidates from last build with compatible structure
2. Attempt to create hot-reloaded template using candidate's pool
3. Score: Count unused dynamic items remaining
4. Select candidate with least unused items
5. Greedy approach optimal because it maximizes reuse

Change Detection

NOT possible:

• Number of rsx! macros changes
• Rust expressions change
• Component structure changes
• Control flow conditions change

IS possible:

• Component children content
• Reordering attributes
• Adding dynamic text segments from pool
• Changing literal values
• Shuffling template structure

Devtools Protocol

WebSocket Communication

Bidirectional WebSocket between app and devserver.

Connection:

• URL: ws://localhost:3000/_dioxus
• Query params: build_id, pid, aslr_reference
• Persistent during development

Message Types

pub enum DevserverMsg {
    HotReload(HotReloadMsg),  // Templates + optional jump table
    HotPatchStart,            // Binary patching starting
    FullReloadStart,          // Rebuilding entire app
    FullReloadFailed,         // Build failed
    FullReloadCommand,        // Full page reload needed
    Shutdown,                 // Devserver shutting down
}

HotReloadMsg Structure

pub struct HotReloadMsg {
    pub templates: Vec<HotReloadTemplateWithLocation>,
    pub assets: Vec<PathBuf>,
    pub ms_elapsed: u64,
    pub jump_table: Option<JumpTable>,
    pub for_build_id: Option<u64>,
    pub for_pid: Option<u32>,
}

Message Processing

1. connect(callback) - Generic connection
2. connect_subsecond() - Subsecond-specific with jump tables
3. apply_changes(dom, msg):
   • Updates signal-based template cache
   • Applies jump table if PID matches
   • Marks all components dirty

WASM-Specific Handling

• Connection at ws://host/_dioxus?build_id={build_id}
• Supports playground mode (iframe via postMessage)
• Console logging sent to devserver
• Page reload on FullReloadCommand
• Asset cache invalidation via dx_force_reload query params

Integration Flow

Subsecond in Dioxus Apps

fn main() {
    dioxus::launch(app);
    // Devtools automatically connects during init
}

For non-Dioxus apps:

fn main() {
    dioxus_devtools::connect_subsecond();

    loop {
        dioxus_devtools::subsecond::call(|| {
            handle_request()
        });
    }
}

Async Integration

#[tokio::main]
async fn main() {
    dioxus_devtools::serve_subsecond_with_args(
        state,
        |state| async {
            app_main(state).await
        }
    ).await;
}

Process:

1. Catches patch message
2. Applies jump table
3. Drops current future
4. Creates new future with hot function
5. Continues execution

Build System Integration

Fat vs Thin Builds

Fat Build (initial):

• Full build with all symbols
• Required for initial symbol table
• Creates HotpatchModuleCache

Thin Build (patches):

• Compiles only modified functions
• Uses cached dependency symbols
• Produces minimal patch dylib

JumpTable Structure

pub struct JumpTable {
    pub lib: PathBuf,              // Path to patch dylib
    pub map: HashMap<u64, u64>,    // old_addr → new_addr
    pub aslr_reference: u64,
    pub new_base_address: u64,
    pub ifunc_count: u32,
}

Platform-Specific Patching

• create_windows_jump_table() - x86/x64 jump stubs
• create_native_jump_table() - macOS/Linux function overrides
• create_wasm_jump_table() - WASM indirect call table updates

Key Design Decisions

1. Jump table indirection: Safe, no memory corruption
2. Conservative RSX diffing: Rust changes trigger rebuild
3. Greedy pool matching: Optimal template reuse
4. WebSocket protocol: Real-time bidirectional updates
5. PID filtering: Correct process receives patches
6. Dual system: RSX for templates, Subsecond for logic

Future Considerations

Workspace Support

• Dependency graph analysis for affected crates
• Incremental library crate compilation
• Cross-crate function pointer resolution

Remote Hot-Reloading

• SCP transport for bandwidth efficiency
• Binary diff for minimal transfers
• Cryptographic verification

CLI Tunnels

• SSH/TCP protocol wrapping
• Connection persistence
• Latency-tolerant queueing