From 19bc43020d6afa2265447e2dad43ad617812ab38 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 10 Dec 2016 10:49:39 +0200 Subject: [PATCH] Documentation and commentary improvements * src/lisp.h: * src/regex.c: * src/xgselect.c (xg_select): Improve commentary and formatting. * doc/lispref/objects.texi (Thread Type, Mutex Type) (Condition Variable Type): New subsections. (Type Predicates): Add thread-related predicates. * doc/lispref/objects.texi (Editing Types): * doc/lispref/elisp.texi (Top): Update higher-level menus. --- doc/lispref/elisp.texi | 3 ++ doc/lispref/objects.texi | 69 ++++++++++++++++++++++++++++++++++++++++ src/lisp.h | 2 ++ src/regex.c | 1 + src/xgselect.c | 3 ++ 5 files changed, 78 insertions(+) diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 415dbe66fac..4a53a0cd364 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -349,6 +349,9 @@ Editing Types * Window Configuration Type:: Recording the way a frame is subdivided. * Frame Configuration Type:: Recording the status of all frames. * Process Type:: A subprocess of Emacs running on the underlying OS. +* Thread Type:: A thread of Emacs Lisp execution. +* Mutex Type:: An exclusive lock for thread synchronization. +* Condition Variable Type:: Condition variable for thread synchronization. * Stream Type:: Receive or send characters. * Keymap Type:: What function a keystroke invokes. * Overlay Type:: How an overlay is represented. diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index a76fbb1af7f..5e608bcc093 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -1410,6 +1410,9 @@ editing. * Window Configuration Type:: Recording the way a frame is subdivided. * Frame Configuration Type:: Recording the status of all frames. * Process Type:: A subprocess of Emacs running on the underlying OS. +* Thread Type:: A thread of Emacs Lisp execution. +* Mutex Type:: An exclusive lock for thread synchronization. +* Condition Variable Type:: Condition variable for thread synchronization. * Stream Type:: Receive or send characters. * Keymap Type:: What function a keystroke invokes. * Overlay Type:: How an overlay is represented. @@ -1625,6 +1628,63 @@ giving the name of the process: return information about, send input or signals to, and receive output from processes. +@node Thread Type +@subsection Thread Type + + A @dfn{thread} in Emacs represents a separate thread of Emacs Lisp +execution. It runs its own Lisp program, has its own current buffer, +and can have subprocesses locked to it, i.e.@: subprocesses whose +output only this thread can accept. @xref{Threads}. + + Thread objects have no read syntax. They print in hash notation, +giving the name of the thread (if it has been given a name) or its +address in core: + +@example +@group +(all-threads) + @result{} (#) +@end group +@end example + +@node Mutex Type +@subsection Mutex Type + + A @dfn{mutex} is an exclusive lock that threads can own and disown, +in order to synchronize between them. @xref{Mutexes}. + + Mutex objects have no read syntax. They print in hash notation, +giving the name of the mutex (if it has been given a name) or its +address in core: + +@example +@group +(make-mutex "my-mutex") + @result{} # +(make-mutex) + @result{} # +@end group +@end example + +@node Condition Variable Type +@subsection Condition Variable Type + + A @dfn{condition variable} is a device for a more complex thread +synchronization than the one supported by a mutex. A thread can wait +on a condition variable, to be woken up when some other thread +notifies the condition. + + Condition variable objects have no read syntax. They print in hash +notation, giving the name of the condition variable (if it has been +given a name) or its address in core: + +@example +@group +(make-condition-variable (make-mutex)) + @result{} # +@end group +@end example + @node Stream Type @subsection Stream Type @@ -1830,6 +1890,9 @@ with references to further information. @item commandp @xref{Interactive Call, commandp}. +@item condition-variable-p +@xref{Condition Variables, condition-variable-p}. + @item consp @xref{List-related Predicates, consp}. @@ -1875,6 +1938,9 @@ with references to further information. @item markerp @xref{Predicates on Markers, markerp}. +@item mutexp +@xref{Mutexes, mutexp}. + @item wholenump @xref{Predicates on Numbers, wholenump}. @@ -1908,6 +1974,9 @@ with references to further information. @item syntax-table-p @xref{Syntax Tables, syntax-table-p}. +@item threadp +@xref{Basic Thread Functions, threadp}. + @item vectorp @xref{Vectors, vectorp}. diff --git a/src/lisp.h b/src/lisp.h index 72ea50d5f27..3c7c3dde904 100644 --- a/src/lisp.h +++ b/src/lisp.h @@ -845,6 +845,7 @@ enum pvec_type PVEC_THREAD, PVEC_MUTEX, PVEC_CONDVAR, + /* These should be last, check internal_equal to see why. */ PVEC_COMPILED, PVEC_CHAR_TABLE, @@ -3229,6 +3230,7 @@ union specbinding } bt; }; +/* These 3 are defined as macros in thread.h. */ /* extern union specbinding *specpdl; */ /* extern union specbinding *specpdl_ptr; */ /* extern ptrdiff_t specpdl_size; */ diff --git a/src/regex.c b/src/regex.c index e7231d3882b..f1686cf700c 100644 --- a/src/regex.c +++ b/src/regex.c @@ -1140,6 +1140,7 @@ print_double_string (re_char *where, re_char *string1, ssize_t size1, #endif /* not DEBUG */ #ifndef emacs + /* Set by `re_set_syntax' to the current regexp syntax to recognize. Can also be assigned to arbitrarily: each pattern buffer stores its own syntax, so it can be changed between regex compilations. */ diff --git a/src/xgselect.c b/src/xgselect.c index e418e1a3c4e..2f23764ae41 100644 --- a/src/xgselect.c +++ b/src/xgselect.c @@ -76,6 +76,9 @@ xg_select (int fds_lim, fd_set *rfds, fd_set *wfds, fd_set *efds, if (gfds_size < n_gfds) { + /* Avoid using SAFE_NALLOCA, as that implicitly refers to the + current thread. Using xnmalloc avoids thread-switching + problems here. */ gfds = xnmalloc (n_gfds, sizeof *gfds); must_free = 1; gfds_size = n_gfds; -- 2.39.5