X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/87c6b4e6bd7e023bd57c709bb6af59bca27bf4f6..ec2c4ee6d2cb9c5505f120229269941f064b23fa:/src/w32notify.c

diff --git a/src/w32notify.c b/src/w32notify.c
index afa03498ff..a48a83daf5 100644
--- a/src/w32notify.c
+++ b/src/w32notify.c
@@ -1,5 +1,5 @@
 /* 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.
 
@@ -16,15 +16,18 @@ GNU General Public License for more details.
 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
@@ -36,7 +39,7 @@ along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.  */
    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
@@ -56,12 +59,13 @@ along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.  */
 
    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
@@ -72,9 +76,10 @@ along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.  */
    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>
@@ -124,7 +129,7 @@ send_notifications (BYTE *info, DWORD info_size, void *desc,
 		    volatile int *terminate)
 {
   int done = 0;
-  FRAME_PTR f = SELECTED_FRAME ();
+  struct frame *f = SELECTED_FRAME ();
 
   /* A single buffer is used to communicate all notifications to the
      main thread.  Since both the main thread and several watcher
@@ -185,9 +190,9 @@ watch_end (ULONG_PTR arg)
     }
 }
 
-/* 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)
@@ -212,7 +217,7 @@ 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
@@ -437,8 +442,8 @@ DEFUN ("w32notify-add-watch", Fw32notify_add_watch,
 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:
@@ -471,7 +476,13 @@ following:
   '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;