[Emacs-diffs] /srv/bzr/emacs/trunk r111237: Improve and correct commentary to w32proc-related data and functions.

[Eli Zaretskii]

------------------------------------------------------------
revno: 111237
committer: Eli Zaretskii <address@hidden>
branch nick: trunk
timestamp: Sat 2012-12-15 13:04:14 +0200
message:
  Improve and correct commentary to w32proc-related data and functions.
modified:
  src/callproc.c
  src/w32.c
  src/w32.h
  src/w32proc.c

=== modified file 'src/callproc.c'
--- a/src/callproc.c    2012-12-08 02:30:51 +0000
+++ b/src/callproc.c    2012-12-15 11:04:14 +0000
@@ -1274,7 +1274,7 @@
 #ifdef WINDOWSNT
   prepare_standard_handles (in, out, err, handles);
   set_process_dir (SDATA (current_dir));
-  /* Spawn the child.  (See ntproc.c:Spawnve).  */
+  /* Spawn the child.  (See w32proc.c:sys_spawnve).  */
   cpid = spawnve (_P_NOWAIT, new_argv[0], new_argv, env);
   reset_standard_handles (in, out, err, handles);
   if (cpid == -1)

=== modified file 'src/w32.c'
--- a/src/w32.c 2012-12-14 14:05:01 +0000
+++ b/src/w32.c 2012-12-15 11:04:14 +0000
@@ -6085,7 +6085,8 @@
 }
 
 /* Function to do blocking read of one byte, needed to implement
-   select.  It is only allowed on sockets and pipes. */
+   select.  It is only allowed on communication ports, sockets, or
+   pipes. */
 int
 _sys_read_ahead (int fd)
 {

=== modified file 'src/w32.h'
--- a/src/w32.h 2012-11-21 21:06:52 +0000
+++ b/src/w32.h 2012-12-15 11:04:14 +0000
@@ -68,17 +68,41 @@
    a socket, the process handle in pi is NULL. */
 typedef struct _child_process
 {
-  int                   fd;
-  int                   pid;
-  HANDLE                char_avail;
-  HANDLE                char_consumed;
-  HANDLE                thrd;
-  HWND                  hwnd;
-  PROCESS_INFORMATION   procinfo;
-  volatile int          status;
-  char                  chr;
-  OVERLAPPED            ovl_read;
-  OVERLAPPED            ovl_write;
+  /* File descriptor for sockets and serial port connections, and for
+     reading output from async subprocesses; otherwise -1.  */
+  int                 fd;
+  /* PID for subprocess, either async or not; otherwise -1.  */
+  int                 pid;
+  /* Handle to an event object that is signaled when a read operation
+     is completed, either successfully (in which case there're indeed
+     "characters available") or not.  Used by sys_select to wait for
+     output from subprocesses or socket/serial connections.  */
+  HANDLE              char_avail;
+  /* Handle to an event that is signaled to wake up the reader thread
+     and tell it to try reading more output from a subprocess.  */
+  HANDLE              char_consumed;
+  /* Handle to the reader thread to read output from a subprocess or a
+     socket or a comm port.  */
+  HANDLE              thrd;
+  /* Handle to the console window of a subprocess.  Used to forcibly
+     terminate it by sys_kill.  */
+  HWND                hwnd;
+  /* Information about subprocess returned by CreateProcess.  Includes
+     handles to the subprocess and its primary thread, and the
+     corresponding process ID and thread ID numbers.  The PID is
+     mirrored by the 'pid' member above.  The process handle is used
+     to wait on it.  */
+  PROCESS_INFORMATION procinfo;
+  /* Status of subprocess/connection and of reading its output.  For
+     values, see the enumeration above.  */
+  volatile int        status;
+  /* Holds a single character read by _sys_read_ahead, when a
+     subprocess has some output ready.  */
+  char                chr;
+  /* Used for async read operations on serial comm ports.  */
+  OVERLAPPED          ovl_read;
+  /* Used for async write operations on serial comm ports.  */
+  OVERLAPPED          ovl_write;
 } child_process;
 
 #define MAXDESC FD_SETSIZE

=== modified file 'src/w32proc.c'
--- a/src/w32proc.c     2012-12-10 12:08:02 +0000
+++ b/src/w32proc.c     2012-12-15 11:04:14 +0000
@@ -1857,7 +1857,7 @@
          }
        else
          {
-           /* Child process and socket input */
+           /* Child process and socket/comm port input.  */
            cp = fd_info[i].cp;
            if (cp)
              {
@@ -1870,7 +1870,7 @@
                    /* Wake up the reader thread for this process */
                    cp->status = STATUS_READ_READY;
                    if (!SetEvent (cp->char_consumed))
-                     DebPrint (("nt_select.SetEvent failed with "
+                     DebPrint (("sys_select.SetEvent failed with "
                                 "%lu for fd %ld\n", GetLastError (), i));
                  }