[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
emacs-27 21c3020 2/2: Document some restrictions for module functions.
From: |
Philipp Stephani |
Subject: |
emacs-27 21c3020 2/2: Document some restrictions for module functions. |
Date: |
Thu, 26 Dec 2019 05:32:33 -0500 (EST) |
branch: emacs-27
commit 21c3020fcec0a32122d2680a391864a75393031b
Author: Philipp Stephani <address@hidden>
Commit: Philipp Stephani <address@hidden>
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 c7b9e72..1d03cbd 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