Use ErrEventOverflow instead of "short read in readEvents()"

Fixes #383

backend_fen.go

@@ -110,6 +110,12 @@ type Watcher struct {
 	Events chan Event
 
 	// Errors sends any errors.
+	//
+	// [ErrEventOverflow] is used to indicate ther are too many events:
+	//
+	//  - inotify: there are too many queued events (fs.inotify.max_queued_events sysctl)
+	//  - windows: The buffer size is too small; [WithBufferSize] can be used to increase it.
+	//  - kqueue, fen: not used.
 	Errors chan error
 
 	mu      sync.Mutex

backend_inotify.go

@@ -113,6 +113,12 @@ type Watcher struct {
 	Events chan Event
 
 	// Errors sends any errors.
+	//
+	// [ErrEventOverflow] is used to indicate ther are too many events:
+	//
+	//  - inotify: there are too many queued events (fs.inotify.max_queued_events sysctl)
+	//  - windows: The buffer size is too small; [WithBufferSize] can be used to increase it.
+	//  - kqueue, fen: not used.
 	Errors chan error
 
 	// Store fd here as os.File.Read() will no longer return on close after

backend_kqueue.go

@@ -111,6 +111,12 @@ type Watcher struct {
 	Events chan Event
 
 	// Errors sends any errors.
+	//
+	// [ErrEventOverflow] is used to indicate ther are too many events:
+	//
+	//  - inotify: there are too many queued events (fs.inotify.max_queued_events sysctl)
+	//  - windows: The buffer size is too small; [WithBufferSize] can be used to increase it.
+	//  - kqueue, fen: not used.
 	Errors chan error
 
 	done         chan struct{}

backend_windows.go

@@ -114,6 +114,12 @@ type Watcher struct {
 	Events chan Event
 
 	// Errors sends any errors.
+	//
+	// [ErrEventOverflow] is used to indicate ther are too many events:
+	//
+	//  - inotify: there are too many queued events (fs.inotify.max_queued_events sysctl)
+	//  - windows: The buffer size is too small; [WithBufferSize] can be used to increase it.
+	//  - kqueue, fen: not used.
 	Errors chan error
 
 	port  windows.Handle // Handle to completion port
@@ -665,7 +671,7 @@ func (w *Watcher) readEvents() {
 		var offset uint32
 		for {
 			if n == 0 {
-				w.sendError(errors.New("short read in readEvents()"))
+				w.sendError(ErrEventOverflow)
 				break
 			}
 

fsnotify.go

@@ -40,8 +40,8 @@ const (
 // Common errors that can be reported by a watcher
 var (
 	ErrNonExistentWatch = errors.New("fsnotify: can't remove non-existent watcher")
-	ErrEventOverflow    = errors.New("fsnotify: queue overflow")
 	ErrClosed           = errors.New("fsnotify: watcher already closed")
+	ErrEventOverflow    = errors.New("fsnotify: queue or buffer overflow")
 )
 
 func (o Op) String() string {
@@ -101,7 +101,8 @@ func getOptions(opts ...addOpt) withOpts {
 // for other backends.
 //
 // The default value is 64K (65536 bytes) which should be enough for most
-// applications, but you can increase it if you're hitting "short read" errors.
+// applications, but you can increase it if you're hitting "queue or buffer
+// overflow" errors ([ErrEventOverflow]).
 func WithBufferSize(bytes int) addOpt {
 	return func(opt *withOpts) { opt.bufsize = bytes }
 }

mkdoc.zsh

@@ -184,6 +184,12 @@ EOF
 
 errors=$(<<EOF
 	// Errors sends any errors.
+	//
+	// [ErrEventOverflow] is used to indicate ther are too many events:
+	//
+	//  - inotify: there are too many queued events (fs.inotify.max_queued_events sysctl)
+	//  - windows: The buffer size is too small; [WithBufferSize] can be used to increase it.
+	//  - kqueue, fen: not used.
 EOF
 )