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 c7b9e7286b35af147822823a346eccdd6e327a42..1d03cbd085bd4929c72b4b2b5f216bf04eb608bc 100644 (file)
--- 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