Documentation
¶
Overview ¶
Package notifier provides a grouped event notification mechanism that accumulates filesystem events and errors and triggers user-defined callbacks at controlled intervals.
The Notifier is designed to avoid flooding handlers when many filesystem events happen in quick succession. It supports:
- Event batching with a configurable delay.
- Rate limiting using golang.org/x/time/rate.
- Custom callbacks for events and errors.
- Safe concurrent access and automatic recovery from panics in handlers.
Example usage:
// Create a new notifier with a delay of 200ms and up to 5 events per delay
notifier, err := notifier.Create(paths,
notifier.OnPaths("/tmp/watchdir"),
notifier.WithEventHandler(func(path string, events []fsnotify.Event) {
fmt.Println("Received events:", events)
}),
notifier.WithLimitDelay(200*time.Millisecond),
notifier.WithBurstNumber(5),
)
if err != nil {
log.Fatal(err)
}
// Start watching
err = notifier.Start()
if err != nil {
log.Fatal(err)
}
defer notifier.Close()
Index ¶
- type Event
- type Notifier
- type Option
- func ForOperations(ops ...fsnotify.Op) Option
- func OnPath(path string) Option
- func OnPaths(paths ...string) Option
- func WatchSubfolders(enabled bool) Option
- func WithBurstNumber(burst uint) Option
- func WithEventChainAsHandler(ch chan<- Event) Option
- func WithEventHandler(handler func(string, []fsnotify.Event)) Option
- func WithSimpleHandler(handler func()) Option
- func WithThrottleInterval(interval time.Duration) Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Notifier ¶
type Notifier struct {
// contains filtered or unexported fields
}
Notifier accumulates filesystem events and errors and triggers user-defined callbacks in a rate-limited and batched manner.
It is safe for concurrent use.
func Create ¶
Create creates a new Notifier for the specified filesystem locations.
The notifier will accumulate events and errors from the given paths and trigger configured callbacks according to the delay and event-per-delay settings.
func (*Notifier) AddPath ¶
AddPath adds a new path to the notifier. It must be called before Start. The path must exist on the filesystem, otherwise an error is returned.
type Option ¶
Option is a function type for configuring Notifier.
func ForOperations ¶
ForOperations returns an Option that configures a Notifier to only consider specific filesystem operations for triggering events.
The provided operations (ops) are combined into a set. Only events matching one of these operations will be processed by the Notifier.
Example:
notifier, err := Create(
"/tmp/watchdir",
ForOperations(fsnotify.Create, fsnotify.Write, fsnotify.Remove),
)
if err != nil {
log.Fatal(err)
}
Supported operations are defined in fsnotify.Op:
fsnotify.Create, fsnotify.Write, fsnotify.Remove, fsnotify.Rename, fsnotify.Chmod
This Option can be passed to a Notifier during creation to filter events according to your requirements.
func WatchSubfolders ¶
WatchSubfolders enables or disables recursive monitoring of subfolders.
By default, fsnotify does not watch subfolders of a directory automatically. When enabled, this option ensures that all nested directories are included in the watch scope, so events such as file creation, modification, renaming, or deletion inside subdirectories will also be detected. Parameters:
- enabled: set to true to include subfolders in the watch, false to restrict watching only to the top-level directory.
Returns:
- Option: a configuration function applied when creating the watcher.
func WithBurstNumber ¶
WithBurstNumber sets the maximum number of events allowed per delay window.
func WithEventChainAsHandler ¶ added in v1.4.5
WithEventChainAsHandler sets up an event handler that delivers batched fsnotify events into the provided channel instead of invoking a direct callback.
This option is useful when you prefer to decouple event handling logic from the watcher by processing events asynchronously through a channel. Each emitted Event groups together all fsnotify events for a given path during a batch.
func WithEventHandler ¶
WithEventHandler sets the event handler callback that receives batched fsnotify events.
func WithSimpleHandler ¶
func WithSimpleHandler(handler func()) Option
WithSimpleHandler sets a simple callback invoked when events are accumulated, without event details.
func WithThrottleInterval ¶
WithThrottleInterval sets the throttling interval used to configure the rate limiter. It represents the minimum time between allowed callback invocations.
Source Files