Improve file notifications, especially for Tramp

* doc/lispref/files.texi (Magic File Names):
Mention `file-notify-valid-p'.

* doc/lispref/os.texi (File Notifications):
Describe `file-notify-valid-p'.

* etc/NEWS: Add `file-notify-valid-p'.

* lisp/net/tramp-gvfs.el (tramp-gvfs-handle-file-notify-add-watch):
Improve implementation.
(tramp-gvfs-monitor-file-process-filter): Rename from
`tramp-gvfs-file-gvfs-monitor-file-process-filter'.  Delete
process if appropriate.

* lisp/net/tramp-sh.el (tramp-sh-handle-file-notify-add-watch):
Improve implementation.
(tramp-sh-gvfs-monitor-dir-process-filter): Rename from
`tramp-sh-file-gvfs-monitor-dir-process-filter'.  Delete process
if appropriate.
(tramp-sh-inotifywait-process-filter): Rename from
`tramp-sh-file-inotifywait-process-filter'.  Delete process if
appropriate.

* lisp/net/tramp.el (tramp-handle-file-notify-rm-watch):
Use `delete-process'
(tramp-handle-file-notify-valid-p): Check also, that file or
directory to be watched still exists.

* test/automated/file-notify-tests.el (file-notify--test-timeout):
New defun.  Use it at all places a timeout is needed.
(file-notify--test-cleanup): Delete directories recursively.
Cleanup also Tramp connections.
(file-notify-test02-events): Add tests for `attribute-change'.
(file-notify-test04-file-validity, file-notify-test05-dir-validity):
Add tests for `file-notify-rm-watch'.

2 files changed, 13 insertions, 0 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index ffc7936107b..db2ecc08f95 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2854,6 +2854,7 @@ first, before handlers for jobs such as remote file access.
 @code{file-name-nondirectory},
 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
 @code{file-notify-add-watch}, @code{file-notify-rm-watch},
+@code{file-notify-valid-p},
 @code{file-ownership-preserved-p},
 @code{file-readable-p}, @code{file-regular-p},
 @code{file-remote-p}, @code{file-selinux-context},
@@ -2907,6 +2908,7 @@ first, before handlers for jobs such as remote file access.
 @code{file-name-nondirec@discretionary{}{}{}tory},
 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
 @code{file-notify-add-watch}, @code{file-notify-rm-watch},
+@code{file-notify-valid-p},
 @code{file-ownership-pre@discretionary{}{}{}served-p},
 @code{file-readable-p}, @code{file-regular-p},
 @code{file-remote-p}, @code{file-selinux-context},
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index cb583038979..f5eecb2d569 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -2692,6 +2692,17 @@ Removes an existing file watch specified by its @var{descriptor}.
 @code{file-notify-add-watch}.
 @end defun
 
+@defun file-notify-valid-p descriptor
+Checks a watch specified by its @var{descriptor} for validity.
+@var{descriptor} should be an object returned by
+@code{file-notify-add-watch}.
+
+A watch can become invalid if the file or directory it watches is
+deleted, or if the watcher thread exits abnormally for any other
+reason.  Removing the watch by calling @code{file-notify-rm-watch}
+also makes it invalid.
+@end defun
+
 @node Dynamic Libraries
 @section Dynamically Loaded Libraries
 @cindex dynamic libraries