Documentation
¶
Overview ¶
Package watcher monitors a directory tree for filesystem changes and delivers batched, debounced events to callers.
Watcher is the interface; New selects an implementation based on config.Config.WatchMode: "fsnotify" for kernel-level notifications (kqueue on macOS/BSD, inotify on Linux), "poll" for periodic directory scanning, or "auto" which tries kernel-level watching and falls back to polling. Event carries the changed path and Op type.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrEventOverflow = errors.New("watcher: queue or buffer overflow") ErrNonExistentWatch = errors.New("watcher: can't remove non-existent watch") ErrClosed = errors.New("watcher: watcher already closed") )
Sentinel errors for watcher backend conditions.
Functions ¶
func IsWatchLimitError ¶
IsWatchLimitError reports whether err is an OS-level watch-limit error. On Linux this is ENOSPC (inotify watch table full); on macOS it is EMFILE (per-process file descriptor limit) or ENFILE (system-wide limit).
Types ¶
type Op ¶
type Op int
Op is the type of filesystem change.
const ( // Create signals a new file was created. Create Op = iota // Write signals an existing file was modified. Write // Remove signals a file was deleted. Remove // Rename signals a file was renamed or moved. Rename // Reindex signals that the watcher detected a potential event loss // (e.g. inotify queue overflow) and a full re-index should be performed // to recover potentially missed changes. Reindex )
type Watcher ¶
type Watcher interface {
// Watch returns a channel of batched, debounced events.
// The channel is closed when ctx is cancelled or Close is called.
// Watch must be called exactly once per Watcher instance.
Watch(ctx context.Context) <-chan []Event
Close() error
}
Watcher monitors a directory tree for file changes. Watch must be called exactly once; calling it a second time is not safe.
func New ¶
New creates a Watcher based on cfg.WatchMode:
- "poll": polling watcher
- "fsnotify": kernel-level watcher (errors if unavailable)
- "auto" or "": attempts kernel-level watching; falls back to polling on error, watch limit, or failed event-delivery probe
matchFn, when non-nil, is called to decide whether a file path should produce events. Pass nil to use the include/exclude pattern logic only. fsys is the filesystem to walk; pass w.FS() (the walker's os.Root-scoped FS) for production use to prevent symlink-escape attacks.
Source Files