Documentation
¶
Overview ¶
Package fswatch is Silk's filesystem-watcher runtime — the equivalent of Qt's QFileSystemWatcher. Apps register paths (files or directories) via AddPath; the Watcher polls them on a background goroutine and delivers Event values on its Events channel when a file is created, modified, or removed.
Why polling and not fsnotify / inotify / FSEvents? Two reasons:
- No third-party deps. Silk's design philosophy is "pure Go + CGO only for Cairo / GLFW / SQLite". A native event API would pull in fsnotify (with its own per-OS C bindings), which we can't justify for the typical UI use case (config files, theme reload, IDE auto-rebuild on save).
- Determinism. Polling sees coalesced events — a file rapidly written multiple times surfaces as a single Modified event, which is what hosts usually want anyway. Native event APIs produce one event per write and the host has to debounce manually.
Cost: PollInterval-bounded latency for change detection. The default 500ms is fast enough for hot reload + slow enough that polling cost is negligible (a stat call per watched path per 500ms).
Typical usage:
w := fswatch.New()
defer w.Stop()
w.AddPath("/path/to/config.json")
w.AddPath("/path/to/templates") // directory
go func() {
for ev := range w.Events() {
switch ev.Kind {
case fswatch.Modified:
reloadConfig(ev.Path)
case fswatch.Created:
indexNewTemplate(ev.Path)
case fswatch.Removed:
forgetFile(ev.Path)
}
}
}()
The Events channel is buffered (default 64); slow consumers risk dropped events and will see a gap in the sequence. Hosts that can't keep up should drain on a dedicated goroutine and forward to their own buffered queue.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Event ¶
Event is a single filesystem-change report. Path is the absolute path of the changed entry; ModTime is the filesystem-reported modification time at observation (zero on Removed). Kind tells the consumer what happened.
type EventKind ¶
type EventKind int
EventKind enumerates the change types a Watcher detects. Mirrors QFileSystemWatcher's two-event split (fileChanged / directoryChanged) expanded into Created/Modified/Removed for finer-grain handling — most consumers want to know whether a path appeared or vanished.
const ( // Created fires when a path inside a watched directory appears. // Never fires for directly-watched files (you can't observe // "creation" of a file you're already watching). Created EventKind = iota + 1 // Modified fires when a watched file's mtime or size changes, // or when a child of a watched directory is rewritten. Modified // Removed fires when a watched path or a directory child // disappears. After a directly-watched path emits Removed, the // Watcher continues polling so a re-creation can be reported as // Modified (or re-emit Removed if it stays gone). Removed )
type Watcher ¶
type Watcher struct {
// contains filtered or unexported fields
}
Watcher is the central object. Construct with New, then AddPath to register watch targets. The polling goroutine starts on the first AddPath; Stop terminates it and closes the Events channel.
Concurrency: AddPath / RemovePath / Stop are safe to call from any goroutine. Events is read-only; the producer goroutine is the polling loop.
func New ¶
func New() *Watcher
New creates a stopped Watcher with the default 500ms poll interval and a 64-slot event buffer. AddPath starts the polling loop on the first call.
func (*Watcher) AddPath ¶
AddPath registers path (file or directory). Errors from Stat are returned to the caller; the path is added regardless and a Removed event will fire if it later appears and disappears.
Adding the same path twice is a no-op — duplicate watches don't produce duplicate events.
func (*Watcher) Events ¶
Events returns the read-only channel that the polling goroutine publishes on. Closed when Stop returns.
func (*Watcher) Paths ¶
Paths returns the currently-watched absolute paths. Order is map- iteration (unstable) — callers needing a stable list should sort.
func (*Watcher) PollInterval ¶
PollInterval returns the current polling cadence.
func (*Watcher) RemovePath ¶
RemovePath drops the path from the watch list. Does not retroactively emit any events. No-op when path was never added.
func (*Watcher) SetPollInterval ¶
SetPollInterval overrides the default 500ms cadence. Call before AddPath; the goroutine reads pollInterval at start and changes don't apply mid-run. Minimum 50ms — sub-50ms intervals churn the scheduler without measurable gain.