windows: use ErrEventOverflow instead of "short read in readEvents()"

CHANGELOG.md

@@ -28,13 +28,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   up as a fsnotify.Write event. This is never useful, and could result in many
   spurious Write events.
 
+- windows: return ErrEventOverflow if the buffer is full ([#525])
+
+  Before it would merely return "short read", making it hard to detect this
+  error.
+
 - all: return ErrClosed on Add() when the watcher is closed ([#516])
 
 
 [#371]: https://github.com/fsnotify/fsnotify/pull/371
 [#516]: https://github.com/fsnotify/fsnotify/pull/516
 [#518]: https://github.com/fsnotify/fsnotify/pull/518
 [#520]: https://github.com/fsnotify/fsnotify/pull/520
+[#525]: https://github.com/fsnotify/fsnotify/pull/525
 
 ## [1.6.0] - 2022-10-13
 

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.
+	//  - 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.
+	//  - 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.
+	//  - 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.
+	//  - kqueue, fen: not used.
 	Errors chan error
 
 	port  windows.Handle // Handle to completion port
@@ -643,7 +649,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

@@ -47,7 +47,7 @@ const (
 // Common errors that can be reported.
 var (
 	ErrNonExistentWatch = errors.New("fsnotify: can't remove non-existent watcher")
-	ErrEventOverflow    = errors.New("fsnotify: queue overflow")
+	ErrEventOverflow    = errors.New("fsnotify: queue or buffer overflow")
 	ErrClosed           = errors.New("fsnotify: watcher already closed")
 )
 

mkdoc.zsh

@@ -171,6 +171,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.
+	//  - kqueue, fen: not used.
 EOF
 )