/* Filesystem notifications support for GNU Emacs on the Microsoft Windows API.
- Copyright (C) 2012 Free Software Foundation, Inc.
+ Copyright (C) 2012-2013 Free Software Foundation, Inc.
This file is part of GNU Emacs.
You should have received a copy of the GNU General Public License
along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. */
-/* Design overview:
+/* Written by Eli Zaretskii <eliz@gnu.org>.
+
+ Design overview:
For each watch request, we launch a separate worker thread. The
worker thread runs the watch_worker function, which issues an
- asynchronous call to ReadDirectoryChangesW, and then waits for that
- call to complete in SleepEx. Waiting in SleepEx puts the thread in
- an alertable state, so it wakes up when either (a) the call to
- ReadDirectoryChangesW completes, or (b) the main thread instructs
- the worker thread to terminate by sending it an APC, see below.
+ asynchronous call to ReadDirectoryChangesW, and then waits in
+ SleepEx for that call to complete. Waiting in SleepEx puts the
+ thread in an "alertable" state, so it wakes up when either (a) the
+ call to ReadDirectoryChangesW completes, or (b) the main thread
+ instructs the worker thread to terminate by sending it an APC, see
+ below.
When the ReadDirectoryChangesW call completes, its completion
routine watch_completion is automatically called. watch_completion
return, and watch_worker then issues another call to
ReadDirectoryChangesW. (Except when it does not, see below.)
- In a GUI session, The WM_EMACS_FILENOTIFY message, posted to the
+ In a GUI session, the WM_EMACS_FILENOTIFY message posted to the
message queue gets dispatched to the main Emacs window procedure,
which queues it for processing by w32_read_socket. When
w32_read_socket sees this message, it accesses the buffer with file
When the FILE_NOTIFY_EVENT event is processed by keyboard.c's
kbd_buffer_get_event, it is converted to a Lispy event that can be
- bound to a command. The default binding is w32notify-handle-event,
+ bound to a command. The default binding is file-notify-handle-event,
defined on subr.el.
- After w32_read_socket or w32_console_read_socket is done processing
- the notifications, it resets a flag signaling to all watch worker
- threads that the notifications buffer is available for more input.
+ After w32_read_socket or w32_console_read_socket are done
+ processing the notifications, they reset a flag signaling to all
+ watch worker threads that the notifications buffer is available for
+ more input.
When the watch is removed by a call to w32notify-rm-watch, the main
thread requests that the worker thread terminates by queuing an APC
watch_completion function is called one last time with the
ERROR_OPERATION_ABORTED status, which causes it to clean up and set
a flag telling watch_worker to exit without issuing another
- ReadDirectoryChangesW call. The main thread waits for some time
- for the worker thread to exit, and if it doesn't, terminates it
- forcibly. */
+ ReadDirectoryChangesW call. Since watch_worker is the thread
+ procedure of the worker thread, exiting it causes the thread to
+ exit. The main thread waits for some time for the worker thread to
+ exit, and if it doesn't, terminates it forcibly. */
#include <stddef.h>
#include <errno.h>
}
}
-/* A completion routine (a.k.a. APC function) for handling events read
- by ReadDirectoryChangesW. Called by the OS when the thread which
- issued the asynchronous ReadDirectoryChangesW call is in the
+/* A completion routine (a.k.a. "APC function") for handling events
+ read by ReadDirectoryChangesW. Called by the OS when the thread
+ which issued the asynchronous ReadDirectoryChangesW call is in the
"alertable state", i.e. waiting inside SleepEx call. */
VOID CALLBACK
watch_completion (DWORD status, DWORD bytes_ret, OVERLAPPED *io_info)
/* We've been called because the main thread told us to issue
CancelIo on the directory we watch, and watch_end did so.
The directory handle is already closed. We should clean up
- and exit, signalling to the thread worker routine not to
+ and exit, signaling to the thread worker routine not to
issue another call to ReadDirectoryChangesW. Note that we
don't free the dirwatch object itself nor the memory consumed
by its buffers; this is done by the main thread in
This arranges for filesystem events pertaining to FILE to be reported
to Emacs. Use `w32notify-rm-watch' to cancel the watch.
-Value is a descriptor for the added watch, or nil if the file
-cannot be watched.
+Value is a descriptor for the added watch. If the file cannot be
+watched for some reason, this function signals a `file-error' error.
FILTER is a list of conditions for reporting an event. It can include
the following symbols:
'renamed-from' -- a file was renamed whose old name was FILE
'renamed-to' -- a file was renamed and its new name is FILE
-FILE is the name of the file whose event is being reported. */)
+FILE is the name of the file whose event is being reported.
+
+Note that some networked filesystems, such as Samba-mounted Unix
+volumes, might not send notifications about file changes. In these
+cases, this function will return a valid descriptor, but notifications
+will never come in. Volumes shared from remote Windows machines do
+generate notifications correctly, though. */)
(Lisp_Object file, Lisp_Object filter, Lisp_Object callback)
{
Lisp_Object encoded_file, watch_object, watch_descriptor;
HCoop / bpt / emacs.git / blobdiff