Documentation
¶
Overview ¶
Package hotreload bridges silk/fswatch with silk/decl so designer- authored .silkui files can be edited at runtime and trigger an in-process widget tree rebuild without restarting the host process.
Architecture:
- Caller registers a path via Reloader.Watch(path).
- fswatch.Watcher polls the path and emits Modified events.
- The reload loop reads the event, re-parses the file via core.LoadTDocFile + decl.FromTDoc, and dispatches a Reload callback carrying the fresh *decl.Node tree.
- The host application's callback is responsible for the actual widget swap — typically via (*decl.Node).Build() and an app-specific Replace() that rewires parent/children.
The package deliberately stops at "produce the new AST" — performing the widget tree swap is host policy (some apps want a full re-Build, others a smarter diff that preserves scroll positions / focused fields).
Concurrency contract: Reload callbacks fire on the package's reader goroutine, NOT the GLFW main thread. Hosts that touch GLFW state inside the callback must marshal the work onto the main thread (e.g. via gui.RunOnMain or a channel they drain in their event loop). The package documentation calls this out so users don't run a Build() off-thread and crash on first GL call.
Debouncing: rapid successive writes (editor save batches, atomic rename + write) are coalesced inside a small debounce window (default 100ms). Without this every Vim-style save would fire two reloads (one for the temp file rename, one for the actual write).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ErrorFunc ¶
ErrorFunc is invoked for every parse / load / host-callback failure. Hosts typically log to a console panel or flash a banner; returning from the func has no side effect — the loop continues.
type Options ¶
type Options struct {
// Debounce coalesces rapid Modified events on the same path into a
// single rebuild. Useful for editors that write atomically (rename
// temp + chmod + replace) and produce a burst of fs events.
Debounce time.Duration
// PollInterval overrides the underlying fswatch poll cadence.
PollInterval time.Duration
// AllowedExt restricts which file extensions trigger a rebuild.
// Empty means "all files at registered paths". When set, only
// files whose extension matches one of the entries (case-
// insensitive, leading '.' optional) are reloaded — useful when
// a host watches a directory containing both .silkui and unrelated
// scratch files.
AllowedExt []string
}
Options configures a Reloader at construction time. Zero values behave reasonably: Debounce defaults to 100ms; PollInterval defaults to fswatch.New()'s 500ms.
type ReloadFunc ¶
ReloadFunc is the host callback invoked when a watched file successfully re-parses. The first argument is the path that triggered the reload; the second is the fresh AST. The host owns deciding how to apply it (full rebuild, partial diff, etc.).
If the host returns an error, it is forwarded to the optional ErrorFunc so users can surface reload failures in their UI without stopping the watcher.
type Reloader ¶
type Reloader struct {
// contains filtered or unexported fields
}
Reloader is the entry point. Construct via New, register paths via Watch, and Stop on shutdown.
Reloader is safe for concurrent calls to Watch/Unwatch/Stop, but the callbacks run on a single internal goroutine — host callback code does not need its own locking *between* reload calls.
func New ¶
func New(onReload ReloadFunc, onError ErrorFunc, opts Options) (*Reloader, error)
New constructs a Reloader with the given handlers and options. onReload is required; onError may be nil (failures are silently swallowed in that case).
func (*Reloader) Stop ¶
func (r *Reloader) Stop()
Stop halts the reload loop and the underlying watcher. Returns when the goroutines have exited and pending callbacks (if any) have completed. Idempotent.
func (*Reloader) Unwatch ¶
Unwatch removes a previously-watched path. Pending debounced rebuilds for that path are cancelled.