Don't poll auto-revert files that use notification (bug#35418)

It is a waste to periodically poll files that use change notification
in auto-revert mode; stop doing that.  If no files need polling,
turn off the periodic execution entirely to further avoid wasting power.
Use a timer to inhibit immediate reversion for some time after a
notification, for throttling.

This change does not apply to files in global-auto-revert-mode, where
polling is still necessary.  It is disabled by default, and enabled by
setting `auto-revert-avoid-polling' to non-nil.

* lisp/autorevert.el
(toplevel): Require cl-lib.
(auto-revert-avoid-polling, auto-revert--polled-buffers)
(auto-revert--need-polling-p, auto-revert--lockout-interval)
(auto-revert--lockout-timer, auto-revert--end-lockout): New.
(global-auto-revert-mode): Keep notifiers for buffers in auto-revert mode.
(auto-revert-set-timer): Use auto-revert--need-polling-p.
(auto-revert-notify-handler): Restart polling if notification stopped.
Use new lockout timer.
(auto-revert-buffers):
Use auto-revert--polled-buffers and auto-revert--need-polling-p.
(auto-revert-buffers-counter, auto-revert-buffers-counter-lockedout):
Remove.

* etc/NEWS (Changes in Specialized Modes and Packages):
Describe the new auto-revert-avoid-polling variable.

* doc/emacs/files.texi (Reverting):
Add paragraph describing auto-revert-avoid-polling.

1 files changed, 14 insertions, 0 deletions

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index a57428230cc..990b8f16795 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -988,6 +988,20 @@ the polling interval through the variable @code{auto-revert-interval}.
 supported, @code{auto-revert-use-notify} will be @code{nil} by
 default.
 
+@vindex auto-revert-avoid-polling
+@vindex auto-revert-notify-exclude-dir-regexp
+  By default, Auto-Revert mode will poll files for changes
+periodically even when file notifications are used.  Such polling is
+usually unnecessary, and turning it off may save power by relying on
+notifications only.  To do so, set the variable
+@code{auto-revert-avoid-polling} to non-@code{nil}.  However,
+notification is ineffective on certain file systems; mainly network
+file system on Unix-like machines, where files can be altered from
+other machines.  To force polling when
+@code{auto-revert-avoid-polling} is non-@code{nil}, set
+@code{auto-revert-notify-exclude-dir-regexp} to match files that
+should be excluded from using notification.
+
   One use of Auto-Revert mode is to ``tail'' a file such as a system
 log, so that changes made to that file by other programs are
 continuously displayed.  To do this, just move the point to the end of