From: Philipp Stephani <phst@google.com>
Date: Thu, 26 Dec 2019 10:31:51 +0000 (+0100)
Subject: Document some restrictions for module functions.
X-Git-Tag: emacs-27.0.90~282
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=21c3020fce;p=emacs.git

Document some restrictions for module functions.

* doc/lispref/internals.texi (Module Functions): Document some
restrictions for module functions.
---

diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index c7b9e7286b3..1d03cbd085b 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -1403,6 +1403,22 @@ the function to that symbol.  Note that it is possible to use
 @code{fset} instead of @code{defalias}; the differences are described
 in @ref{Defining Functions, defalias}.
 
+Module functions including the @code{emacs_module_init} function
+(@pxref{module initialization function}) may only interact with Emacs
+by calling environment functions from some live @code{emacs_env}
+pointer while being called directly or indirectly from Emacs.  In
+other words, if a module function wants to call Lisp functions or
+Emacs primitives, convert @code{emacs_value} objects to and from C
+datatypes (@pxref{Module Values}), or interact with Emacs in any other
+way, some call from Emacs to @code{emacs_module_init} or to a module
+function must be in the callstack.  Module function may not interact
+with Emacs while garbage collection is running; @pxref{Garbage
+Collection}.  They may only interact with Emacs from Lisp interpreter
+threads (including the main thread) created by Emacs; @pxref{Threads}.
+The @kbd{--module-assertions} command-line option can detect some
+violations of the above requirements.  @xref{Initial Options,,,emacs,
+The GNU Emacs Manual}.
+
 Using the module @acronym{API}, it is possible to define more complex
 function and data types: interactive functions, inline functions,
 macros, etc.  However, the resulting C code will be cumbersome and