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

Extracted from #521; we want to do this no matter what.

Fixes #383

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 52533c09e7836da86b98017b0bb35fc5f086c4e1..434621607c49f98bf29d792102c3e82dbd549edf 100644 (file)
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -28,6 +28,11 @@ 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])
 
 
@@ -35,6 +40,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#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
 

diff --git a/backend_fen.go b/backend_fen.go
index ad7dac97a9a7713251623cb330ca2f1ff403b81f..b66bd3735d83877c39afa73bc00b74472a128939 100644 (file)
--- a/backend_fen.go
+++ b/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

diff --git a/backend_inotify.go b/backend_inotify.go
index 355729a0e0620e32d86998d8a0e8481cd86fc940..9581115620507c15be8a2af7440adadd9ab89c6a 100644 (file)
--- a/backend_inotify.go
+++ b/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

diff --git a/backend_kqueue.go b/backend_kqueue.go
index 348ef63828e872a66edcfb2dae1710bda1fa59b7..00d07dac2c30a03e9754aa06cd7d8b4730a4674b 100644 (file)
--- a/backend_kqueue.go
+++ b/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{}

diff --git a/backend_windows.go b/backend_windows.go
index 1bdadf3a2b31209bd9b58ad5775098f7ff02ff89..3f7e18368fcaaf06e657be43eeee7bb4f7923101 100644 (file)
--- a/backend_windows.go
+++ b/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
                        }
 

diff --git a/fsnotify.go b/fsnotify.go
index 2b570fac371b7b8771ecc144d1dbe0c6c321c858..37b343154ca03599668789d00c5e1a578917f453 100644 (file)
--- a/fsnotify.go
+++ b/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")
 )
 

diff --git a/mkdoc.zsh b/mkdoc.zsh
index a0659b0c88c6a9875294323465c691bade24fd9f..157f425c5f6c2f0d21a892de1fd478cdae0d739c 100755 (executable)
--- a/mkdoc.zsh
+++ b/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
 )