rhaj/rhai_system/examples/hot_reload/README.md

Hot Reload Example

This example demonstrates hot reloading of multiple Rhai script files using the rhai_system crate. It shows how to:

1. Load and execute multiple script files
2. Watch for changes to these files
3. Automatically reload scripts when they change
4. Call functions across different script files

How It Works

The example uses two main components:

1. The System: Created by create_hot_reloadable_system which:

   • Loads multiple script files (script.rhai and utils.rhai)
   • Compiles them into a single AST
   • Sets up file watchers for each script file
   • Provides a clean API for calling functions

2. Two Threads:

   • Execution Thread: Continuously executes functions from the scripts
   • Modification Thread: Modifies the script files at specific intervals to demonstrate hot reloading

Cross-Script Function Calls

The example demonstrates how functions in one script can call functions in another:

• script.rhai contains the main functions (greet, advanced_calculation, multiply, divide)
• utils.rhai contains utility functions (calculate, greet_from_utils)
• Functions in script.rhai call functions in utils.rhai

This shows how you can organize your code into multiple script files while still maintaining the ability to call functions across files.

Running the Example

To run this example, navigate to the root of the rhai_system project and execute:

cargo run --example hot_reload

What to Expect

When you run the example, you'll see:

1. The system loads both script.rhai and utils.rhai
2. The execution thread calls functions from the scripts every second
3. After 5 seconds, the modification thread updates script.rhai to add new functions
4. The execution thread automatically starts using the updated script
5. After another 5 seconds, both script files are modified again
6. The system reloads both scripts and the execution thread uses the latest versions

This demonstrates how the system automatically detects and reloads scripts when they change, without requiring any restart of the application.

Key Implementation Details

Multiple Script Support

The system supports multiple script files through:

// Create a hot reloadable system with multiple script files
let script_paths = vec![
    PathBuf::from("examples/hot_reload/script.rhai"),
    PathBuf::from("examples/hot_reload/utils.rhai"),
];
let system = create_hot_reloadable_system(&script_paths, None).unwrap();

File Watching

The system automatically sets up file watchers for all script files:

// Start watching for changes to the script files
system.watch();

Thread-Safe Usage

The system is thread-safe and can be used from multiple threads:

// Clone the system for use in another thread
let system_clone = Arc::clone(&system);

// Create a thread-local clone for the execution thread
let thread_system = system_clone.clone_for_thread();

Modifying Scripts at Runtime

The example includes functions to modify the script files programmatically:

// Modify the script file with new content
modify_script(
    &script_path,
    "examples/hot_reload/modified_script.rhai",
    5,
    "Modifying the script to add multiply function..."
);

This simulates a developer editing the script files during development, demonstrating how the system automatically detects and reloads the scripts.