Commit f282b9f7 authored by Eli Zaretskii's avatar Eli Zaretskii
Browse files

Proof-read comments on w32notify.c. Adapt NEWS entry.

parent 3907e630
...@@ -136,7 +136,8 @@ spurious warnings about an unused var. ...@@ -136,7 +136,8 @@ spurious warnings about an unused var.
** Support for filesystem notifications. ** Support for filesystem notifications.
Emacs now supports notifications of filesystem changes, such as Emacs now supports notifications of filesystem changes, such as
creation, modification, and deletion of files. This requires the creation, modification, and deletion of files. This requires the
'inotify' API on GNU/Linux systems. 'inotify' API on GNU/Linux systems. On MS-Windows systems, this is
supported for Windows XP and newer versions.
** Face changes ** Face changes
......
...@@ -16,15 +16,18 @@ GNU General Public License for more details. ...@@ -16,15 +16,18 @@ GNU General Public License for more details.
You should have received a copy of the GNU General Public License You should have received a copy of the GNU General Public License
along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. */ 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 For each watch request, we launch a separate worker thread. The
worker thread runs the watch_worker function, which issues an worker thread runs the watch_worker function, which issues an
asynchronous call to ReadDirectoryChangesW, and then waits for that asynchronous call to ReadDirectoryChangesW, and then waits in
call to complete in SleepEx. Waiting in SleepEx puts the thread in SleepEx for that call to complete. Waiting in SleepEx puts the
an alertable state, so it wakes up when either (a) the call to thread in an "alertable" state, so it wakes up when either (a) the
ReadDirectoryChangesW completes, or (b) the main thread instructs call to ReadDirectoryChangesW completes, or (b) the main thread
the worker thread to terminate by sending it an APC, see below. instructs the worker thread to terminate by sending it an APC, see
below.
When the ReadDirectoryChangesW call completes, its completion When the ReadDirectoryChangesW call completes, its completion
routine watch_completion is automatically called. watch_completion routine watch_completion is automatically called. watch_completion
...@@ -59,9 +62,10 @@ along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. */ ...@@ -59,9 +62,10 @@ along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. */
bound to a command. The default binding is w32notify-handle-event, bound to a command. The default binding is w32notify-handle-event,
defined on subr.el. defined on subr.el.
After w32_read_socket or w32_console_read_socket is done processing After w32_read_socket or w32_console_read_socket are done
the notifications, it resets a flag signaling to all watch worker processing the notifications, they reset a flag signaling to all
threads that the notifications buffer is available for more input. 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 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 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/>. */ ...@@ -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 watch_completion function is called one last time with the
ERROR_OPERATION_ABORTED status, which causes it to clean up and set ERROR_OPERATION_ABORTED status, which causes it to clean up and set
a flag telling watch_worker to exit without issuing another a flag telling watch_worker to exit without issuing another
ReadDirectoryChangesW call. The main thread waits for some time ReadDirectoryChangesW call. Since watch_worker is the thread
for the worker thread to exit, and if it doesn't, terminates it procedure of the worker thread, exiting it causes the thread to
forcibly. */ 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 <stddef.h>
#include <errno.h> #include <errno.h>
...@@ -185,9 +190,9 @@ watch_end (ULONG_PTR arg) ...@@ -185,9 +190,9 @@ watch_end (ULONG_PTR arg)
} }
} }
/* A completion routine (a.k.a. APC function) for handling events read /* A completion routine (a.k.a. "APC function") for handling events
by ReadDirectoryChangesW. Called by the OS when the thread which read by ReadDirectoryChangesW. Called by the OS when the thread
issued the asynchronous ReadDirectoryChangesW call is in the which issued the asynchronous ReadDirectoryChangesW call is in the
"alertable state", i.e. waiting inside SleepEx call. */ "alertable state", i.e. waiting inside SleepEx call. */
VOID CALLBACK VOID CALLBACK
watch_completion (DWORD status, DWORD bytes_ret, OVERLAPPED *io_info) watch_completion (DWORD status, DWORD bytes_ret, OVERLAPPED *io_info)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment