From 21c3020fcec0a32122d2680a391864a75393031b Mon Sep 17 00:00:00 2001 From: Philipp Stephani Date: Thu, 26 Dec 2019 11:31:51 +0100 Subject: [PATCH] Document some restrictions for module functions. * doc/lispref/internals.texi (Module Functions): Document some restrictions for module functions. --- doc/lispref/internals.texi | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) 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 -- 2.39.2