Raxol.Core.Runtime.Plugins.FileWatcher (Raxol v0.3.0)

View Source

Handles file watching functionality for plugins.

This module provides a public API for monitoring plugin source files and triggering reloads when changes are detected. It delegates to specialized submodules for different aspects of the functionality:

  • FileWatcher.Core: Core setup and state management
  • FileWatcher.Events: Event handling and debouncing
  • FileWatcher.Reload: Plugin reloading logic
  • FileWatcher.Cleanup: Resource cleanup

State

The module maintains state in the following structure:

%{
  plugin_dirs: [String.t()],           # List of directories to watch
  plugin_paths: %{String.t() => String.t()},  # Plugin ID to path mapping
  reverse_plugin_paths: %{String.t() => String.t()},  # Path to plugin ID mapping
  file_watcher_pid: pid() | nil,       # File system watcher process
  file_event_timer: reference() | nil,  # Debounce timer reference
  file_watching_enabled?: boolean()    # File watching status
}

Usage

# Initialize file watching
state = %{
  plugin_dirs: ["plugins"],
  plugin_paths: %{"my_plugin" => "plugins/my_plugin.ex"},
  file_watching_enabled?: false
}

# Setup file watching
{pid, enabled?} = FileWatcher.setup_file_watching(state)
state = %{state | file_watcher_pid: pid, file_watching_enabled?: enabled?}

# Update file watcher with new paths
state = FileWatcher.update_file_watcher(state)

# Cleanup on shutdown
state = FileWatcher.cleanup_file_watching(state)

For more detailed documentation about the module's architecture and internals, see docs/file_watcher.md.

Summary

Functions

Cleans up file watching resources.

Handles debounced file events. Returns updated state after processing events.

Handles file system events. Returns updated state with debounced reload timer if needed.

Creates a new file watcher state.

Reloads a plugin after file changes. Returns :ok on success or {:error, reason} on failure.

Sets up file watching for plugin source files. Returns the updated state with the file watcher PID.

Updates the reverse path mapping for file watching.

Functions

cleanup_file_watching(state)

Cleans up file watching resources.

handle_debounced_events(plugin_id, path, state)

Handles debounced file events. Returns updated state after processing events.

handle_file_event(path, state)

Handles file system events. Returns updated state with debounced reload timer if needed.

new()

Creates a new file watcher state.

reload_plugin(plugin_id, path)

Reloads a plugin after file changes. Returns :ok on success or {:error, reason} on failure.

setup_file_watching(state)

Sets up file watching for plugin source files. Returns the updated state with the file watcher PID.

update_file_watcher(state)

Updates the reverse path mapping for file watching.