; * src/xterm.c: Improve commentary. Describe error handling.

diff --git a/src/xterm.c b/src/xterm.c
index e78ec3c32c02dc7637bdf220ffee9eb895606bf5..cd7c8a35ec8e78adbe9973f7c21450f3d42eaf73 100644 (file)
--- a/src/xterm.c
+++ b/src/xterm.c
@@ -26,6 +26,22 @@ along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.  */
    contains subroutines comprising the redisplay interface, setting up
    scroll bars and widgets, and handling input.
 
+   X WINDOW SYSTEM
+
+   The X Window System is a windowing system for bitmap graphics
+   displays which originated at MIT in 1984.  Version 11, which is
+   currently supported by Emacs, first appeared in September 1987.
+
+   X has a long history and has been developed by many different
+   organizations over the years; at present, it is being primarily
+   developed by the X.Org Foundation.  It is the main window system
+   that Emacs is developed and tested against, and X version 10 was
+   the first window system that Emacs was ported to.  As a consequence
+   of its age and wide availability, X contains many idiosyncrasies,
+   but that has not prevented it from becoming the dominant free
+   window system, and the platform of reference for all GUI code in
+   Emacs.
+
    Some of what is explained below also applies to the other window
    systems that Emacs supports, to varying degrees.  YMMV.
 
@@ -555,7 +571,56 @@ along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.  */
   drop happening with the primary selection and synthetic button
   events (see `x_dnd_do_unsupported_drop').  That function implements
   the OffiX drag-and-drop protocol by default.  See
-  `x-dnd-handle-unsupported-drop' in `x-dnd.el' for more details.  */
+  `x-dnd-handle-unsupported-drop' in `x-dnd.el' for more details.
+
+  DISPLAY ERROR HANDLING
+
+  While error handling under X was originally designed solely as a
+  mechanism for the X server to report fatal errors to clients, most
+  clients (including Emacs) have adopted a system of "error traps" to
+  handle or discard these errors as they arrive.  Discarding errors is
+  usually necessary when Emacs performs an X request that might fail:
+  for example, sending a message to a window that may no longer exist,
+  or might not exist at all.  Handling errors is then necessary when
+  the detailed error must be reported to another piece of code: for
+  example, as a Lisp error.
+
+  It is not acceptable for Emacs to crash when it is sent invalid data
+  by another client, or by Lisp.  As a result, errors must be caught
+  around Xlib functions generating requests containing resource
+  identifiers that could potentially be invalid, such as window or
+  atom identifiers provided in a client message from another program,
+  or a child window ID obtained through XTranslateCoordinates that may
+  refer to a window that has been deleted in the meantime.
+
+  There are two sets of functions used to perform this "error
+  trapping".  Which one should be used depends on what kind of
+  processing must be done on the error.  The first consists of the
+  functions `x_ignore_errors_for_next_request' and
+  `x_stop_ignoring_errors', which ignore errors generated by requests
+  made in between a call to the first function and a corresponding
+  call to the second.  They should be used for simple asynchronous
+  requests that do not require a reply from the X server: using them
+  instead of the second set improves performance, as they simply
+  record a range of request serials to ignore errors from, instead of
+  synchronizing with the X server to handle errors.
+
+  The second set consists of the following functions:
+
+    - x_catch_errors_with_handler
+    - x_catch_errors
+    - x_uncatch_errors_after_check
+    - x_uncatch_errors
+    - x_check_errors
+    - x_had_errors_p
+    - x_clear_errors
+
+  Callers using this set should consult the comment(s) on top of the
+  aformentioned functions.  They should not be used when the requests
+  being made do not require roundtrips to the X server, and obtaining
+  the details of any error generated is unecessary, as
+  `x_uncatch_errors' will always synchronize with the X server, which
+  is a potentially slow operation.  */
 
 #include <config.h>
 #include <stdlib.h>