fswatch

package
v0.1.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2026 License: MIT Imports: 4 Imported by: 0

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:

  1. 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).
  2. 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

type Event struct {
	Path    string
	Kind    EventKind
	ModTime time.Time
}

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
)

func (EventKind) String

func (k EventKind) String() string

String aids debug + log output.

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

func (w *Watcher) AddPath(path string) error

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

func (w *Watcher) Events() <-chan Event

Events returns the read-only channel that the polling goroutine publishes on. Closed when Stop returns.

func (*Watcher) Paths

func (w *Watcher) Paths() []string

Paths returns the currently-watched absolute paths. Order is map- iteration (unstable) — callers needing a stable list should sort.

func (*Watcher) PollInterval

func (w *Watcher) PollInterval() time.Duration

PollInterval returns the current polling cadence.

func (*Watcher) RemovePath

func (w *Watcher) RemovePath(path string)

RemovePath drops the path from the watch list. Does not retroactively emit any events. No-op when path was never added.

func (*Watcher) SetPollInterval

func (w *Watcher) SetPollInterval(d time.Duration)

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.

func (*Watcher) Stop

func (w *Watcher) Stop()

Stop terminates the polling goroutine and closes Events. Safe to call multiple times — the second call is a no-op. Returns when the goroutine has actually exited.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL