Documentation
¶
Overview ¶
Package watcher provides a thin wrapper around fsnotify for watching file system paths. It offers a configurable interface to register event and error handlers, and ensures safe lifecycle management of the watcher.
The NotifyWrapper struct is the main type that manages:
- Configured paths to watch
- Event handlers for file changes
- Error handlers for watcher errors
Example usage:
events := make(chan fsnotify.Event, 1)
errors := make(chan error, 1)
w, err := watcher.NewFSWatcher(
watcher.OnPath("/tmp"),
watcher.WithEventChainAsHandler(events),
watcher.WithErrorChainAsHandler(errors),
)
if err != nil {
log.Fatalf("failed to create watcher: %v", err)
}
if err := w.Start(); err != nil {
log.Fatalf("failed to start watcher: %v", err)
}
go func() {
for {
select {
case e := <-events:
fmt.Println("file event:", e)
case err := <-errors:
fmt.Println("watcher error:", err)
}
}
}
defer w.Close()
Index ¶
- Variables
- type NotifyWrapper
- type Option
- func OnPath(path string) Option
- func OnPaths(paths ...string) Option
- func WithErrorChainAsHandler(eventsCh chan<- error) Option
- func WithErrorEventHandler(handler func(error)) Option
- func WithEventChainAsHandler(eventsCh chan<- fsnotify.Event) Option
- func WithEventHandler(handler func(fsnotify.Event)) Option
Constants ¶
This section is empty.
Variables ¶
var ( // ErrFSWatcherStartedNotAllowingNewPath is returned when trying to add // new paths to a watcher after it has already been started. ErrFSWatcherStartedNotAllowingNewPath = errors.New("watcher already started, cannot add new path") // ErrFSWatcherHasNoPathsConfigured is returned when Start is called // without any paths configured to watch. ErrFSWatcherHasNoPathsConfigured = errors.New("watcher has no paths") )
Functions ¶
This section is empty.
Types ¶
type NotifyWrapper ¶
type NotifyWrapper struct {
// contains filtered or unexported fields
}
NotifyWrapper wraps fsnotify.Watcher and provides higher-level configuration via functional options. It simplifies setting up file system watchers with custom event and error handlers.
It tracks its lifecycle (`started`) and ensures consistent behavior when adding paths or starting multiple times.
func NewFSWatcher ¶
func NewFSWatcher(opts ...Option) (*NotifyWrapper, error)
NewFSWatcher creates a new NotifyWrapper with the given options.
Example:
w, err := watcher.NewFSWatcher(
watcher.OnPath("/tmp"),
watcher.WithEventHandler(func(e fsnotify.Event) { fmt.Println(e) }),
)
if err != nil {
log.Fatal(err)
}
func (*NotifyWrapper) AddPath ¶
func (w *NotifyWrapper) AddPath(path string) error
AddPath adds a new path to the watcher. It must be called before Start. If the watcher has already been started, this returns ErrFSWatcherStartedNotAllowingNewPath.
The path must exist on the filesystem, otherwise an error is returned.
func (*NotifyWrapper) Close ¶
func (w *NotifyWrapper) Close() error
Close stops the watcher and releases resources. It is safe to call multiple times; subsequent calls will simply reset the started flag.
func (*NotifyWrapper) Start ¶
func (w *NotifyWrapper) Start() error
Start initializes the underlying fsnotify.Watcher and begins watching all configured paths. It also launches the event processing goroutine.
Returns ErrFSWatcherHasNoPathsConfigured if no paths were added.
After Start, the watcher cannot accept new paths (AddPath will fail).
type Option ¶
type Option func(*NotifyWrapper) error
Option represents a configuration option that can be applied to a NotifyWrapper.
func WithErrorChainAsHandler ¶
WithErrorChainAsHandler sends all watcher errors to the provided channel. This is useful for external error handling loops.
func WithErrorEventHandler ¶
WithErrorEventHandler sets the error handler that will be called whenever the watcher encounters an error.
func WithEventChainAsHandler ¶
WithEventChainAsHandler sends all file system events to the provided channel. This is useful for external event processing loops.
func WithEventHandler ¶
WithEventHandler sets the event handler that will be called whenever a file system event occurs on a watched path.
Source Files