diff options
Diffstat (limited to 'devdocs/elisp/module-functions.html')
| -rw-r--r-- | devdocs/elisp/module-functions.html | 35 |
1 files changed, 35 insertions, 0 deletions
diff --git a/devdocs/elisp/module-functions.html b/devdocs/elisp/module-functions.html new file mode 100644 index 00000000..68e15773 --- /dev/null +++ b/devdocs/elisp/module-functions.html @@ -0,0 +1,35 @@ + <h4 class="subsection"> Writing Module Functions</h4> <p>The main reason for writing an Emacs module is to make additional functions available to Lisp programs that load the module. This subsection describes how to write such <em>module functions</em>. </p> <p>A module function has the following general form and signature: </p> <dl> <dt id="emacs_function">Function: <em>emacs_value</em> <strong>emacs_function</strong> <em>(emacs_env *<var>env</var>, ptrdiff_t <var>nargs</var>, emacs_value *<var>args</var>, void *<var>data</var>)</em> +</dt> <dd> + <p>The <var>env</var> argument provides a pointer to the <acronym>API</acronym> environment, needed to access Emacs objects and functions. The <var>nargs</var> argument is the required number of arguments, which can be zero (see <code>make_function</code> below for more flexible specification of the argument number), and <var>args</var> is a pointer to the array of the function arguments. The argument <var>data</var> points to additional data required by the function, which was arranged when <code>make_function</code> (see below) was called to create an Emacs function from <code>emacs_function</code>. </p> <p>Module functions use the type <code>emacs_value</code> to communicate Lisp objects between Emacs and the module (see <a href="module-values">Module Values</a>). The <acronym>API</acronym>, described below and in the following subsections, provides facilities for conversion between basic C data types and the corresponding <code>emacs_value</code> objects. </p> <p>A module function always returns a value. If the function returns normally, the Lisp code which called it will see the Lisp object corresponding to the <code>emacs_value</code> value the function returned. However, if the user typed <kbd>C-g</kbd>, or if the module function or its callees signaled an error or exited nonlocally (see <a href="module-nonlocal">Module Nonlocal</a>), Emacs will ignore the returned value and quit or throw as it does when Lisp code encounters the same situations. </p> <p>The header <samp>emacs-module.h</samp> provides the type <code>emacs_function</code> as an alias type for a function pointer to a module function. </p> +</dd> +</dl> <p>After writing your C code for a module function, you should make a Lisp function object from it using the <code>make_function</code> function, whose pointer is provided in the environment (recall that the pointer to the environment is returned by <code>get_environment</code>). This is normally done in the module initialization function (see <a href="module-initialization#module-initialization-function">module initialization function</a>), after verifying the <acronym>API</acronym> compatibility. </p> <dl> <dt id="make_function">Function: <em>emacs_value</em> <strong>make_function</strong> <em>(emacs_env *<var>env</var>, ptrdiff_t <var>min_arity</var>, ptrdiff_t <var>max_arity</var>, emacs_function <var>func</var>, const char *<var>docstring</var>, void *<var>data</var>)</em> +</dt> <dd> + <p>This returns an Emacs function created from the C function <var>func</var>, whose signature is as described for <code>emacs_function</code> above. The arguments <var>min_arity</var> and <var>max_arity</var> specify the minimum and maximum number of arguments that <var>func</var> can accept. The <var>max_arity</var> argument can have the special value <code>emacs_variadic_function</code>, which makes the function accept an unlimited number of arguments, like the <code>&rest</code> keyword in Lisp (see <a href="argument-list">Argument List</a>). </p> <p>The argument <var>data</var> is a way to arrange for arbitrary additional data to be passed to <var>func</var> when it is called. Whatever pointer is passed to <code>make_function</code> will be passed unaltered to <var>func</var>. </p> <p>The argument <var>docstring</var> specifies the documentation string for the function. It should be either an <acronym>ASCII</acronym> string, or a UTF-8 encoded non-<acronym>ASCII</acronym> string, or a <code>NULL</code> pointer; in the latter case the function will have no documentation. The documentation string can end with a line that specifies the advertised calling convention, see <a href="function-documentation">Function Documentation</a>. </p> <p>Since every module function must accept the pointer to the environment as its first argument, the call to <code>make_function</code> could be made from any module function, but you will normally want to do that from the module initialization function, so that all the module functions are known to Emacs once the module is loaded. </p> +</dd> +</dl> <p>Finally, you should bind the Lisp function to a symbol, so that Lisp code could call your function by name. For that, use the module <acronym>API</acronym> function <code>intern</code> (see <a href="module-misc#intern">intern</a>) whose pointer is also provided in the environment that module functions can access. </p> <p>Combining the above steps, code that arranges for a C function <code>module_func</code> to be callable as <code>module-func</code> from Lisp will look like this, as part of the module initialization function: </p> <div class="example"> <pre class="example"> emacs_env *env = runtime->get_environment (runtime); + emacs_value func = env->make_function (env, min_arity, max_arity, + module_func, docstring, data); + emacs_value symbol = env->intern (env, "module-func"); + emacs_value args[] = {symbol, func}; + env->funcall (env, env->intern (env, "defalias"), 2, args); +</pre> +</div> <p>This makes the symbol <code>module-func</code> known to Emacs by calling <code>env->intern</code>, then invokes <code>defalias</code> from Emacs to bind the function to that symbol. Note that it is possible to use <code>fset</code> instead of <code>defalias</code>; the differences are described in <a href="defining-functions">defalias</a>. </p> <p>Module functions including the <code>emacs_module_init</code> function (see <a href="module-initialization#module-initialization-function">module initialization function</a>) may only interact with Emacs by calling environment functions from some live <code>emacs_env</code> 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</code> objects to and from C datatypes (see <a href="module-values">Module Values</a>), or interact with Emacs in any other way, some call from Emacs to <code>emacs_module_init</code> or to a module function must be in the call stack. Module functions may not interact with Emacs while garbage collection is running; see <a href="garbage-collection">Garbage Collection</a>. They may only interact with Emacs from Lisp interpreter threads (including the main thread) created by Emacs; see <a href="threads">Threads</a>. The <kbd>--module-assertions</kbd> command-line option can detect some violations of the above requirements. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Initial-Options.html#Initial-Options">Initial Options</a> in <cite>The GNU Emacs Manual</cite>. </p> <p>Using the module <acronym>API</acronym>, it is possible to define more complex function and data types: inline functions, macros, etc. However, the resulting C code will be cumbersome and hard to read. Therefore, we recommend that you limit the module code which creates functions and data structures to the absolute minimum, and leave the rest for a Lisp package that will accompany your module, because doing these additional tasks in Lisp is much easier, and will produce a much more readable code. For example, given a module function <code>module-func</code> defined as above, one way of making a macro <code>module-macro</code> based on it is with the following simple Lisp wrapper: </p> <div class="lisp"> <pre class="lisp">(defmacro module-macro (&rest args) + "Documentation string for the macro." + (module-func args)) +</pre> +</div> <p>The Lisp package which goes with your module could then load the module using the <code>load</code> primitive (see <a href="dynamic-modules">Dynamic Modules</a>) when the package is loaded into Emacs. </p> <p>By default, module functions created by <code>make_function</code> are not interactive. To make them interactive, you can use the following function. </p> <dl> <dt id="make_interactive">Function: <em>void</em> <strong>make_interactive</strong> <em>(emacs_env *<var>env</var>, emacs_value <var>function</var>, emacs_value <var>spec</var>)</em> +</dt> <dd><p>This function, which is available since Emacs 28, makes the function <var>function</var> interactive using the interactive specification <var>spec</var>. Emacs interprets <var>spec</var> like the argument to the <code>interactive</code> form. <a href="using-interactive">Using Interactive</a>, and see <a href="interactive-codes">Interactive Codes</a>. <var>function</var> must be an Emacs module function returned by <code>make_function</code>. </p></dd> +</dl> <p>Note that there is no native module support for retrieving the interactive specification of a module function. Use the function <code>interactive-form</code> for that. <a href="using-interactive">Using Interactive</a>. It is not possible to make a module function non-interactive once you have made it interactive using <code>make_interactive</code>. </p> <p>If you want to run some code when a module function object (i.e., an object returned by <code>make_function</code>) is garbage-collected, you can install a <em>function finalizer</em>. Function finalizers are available since Emacs 28. For example, if you have passed some heap-allocated structure to the <var>data</var> argument of <code>make_function</code>, you can use the finalizer to deallocate the structure. See <a href="https://www.gnu.org/software/libc/manual/html_node/Basic-Allocation.html#Basic-Allocation">(libc)Basic Allocation</a>, and see <a href="https://www.gnu.org/software/libc/manual/html_node/Freeing-after-Malloc.html#Freeing-after-Malloc">(libc)Freeing after Malloc</a>. The finalizer function has the following signature: </p> <div class="example"> <pre class="example">void finalizer (void *<var>data</var>) +</pre> +</div> <p>Here, <var>data</var> receives the value passed to <var>data</var> when calling <code>make_function</code>. Note that the finalizer can’t interact with Emacs in any way. </p> <p>Directly after calling <code>make_function</code>, the newly-created function doesn’t have a finalizer. Use <code>set_function_finalizer</code> to add one, if desired. </p> <dl> <dt id="emacs_finalizer">Function: <em>void</em> <strong>emacs_finalizer</strong> <em>(void *<var>ptr</var>)</em> +</dt> <dd><p>The header <samp>emacs-module.h</samp> provides the type <code>emacs_finalizer</code> as a type alias for an Emacs finalizer function. </p></dd> +</dl> <dl> <dt id="get_function_finalizer">Function: <em>emacs_finalizer</em> <strong>get_function_finalizer</strong> <em>(emacs_env *<var>env</var>, emacs_value <var>arg</var>)</em> +</dt> <dd><p>This function, which is available since Emacs 28, returns the function finalizer associated with the module function represented by <var>arg</var>. <var>arg</var> must refer to a module function, that is, an object returned by <code>make_function</code>. If no finalizer is associated with the function, <code>NULL</code> is returned. </p></dd> +</dl> <dl> <dt id="set_function_finalizer">Function: <em>void</em> <strong>set_function_finalizer</strong> <em>(emacs_env *<var>env</var>, emacs_value <var>arg</var>, emacs_finalizer <var>fin</var>)</em> +</dt> <dd><p>This function, which is available since Emacs 28, sets the function finalizer associated with the module function represented by <var>arg</var> to <var>fin</var>. <var>arg</var> must refer to a module function, that is, an object returned by <code>make_function</code>. <var>fin</var> can either be <code>NULL</code> to clear <var>arg</var>’s function finalizer, or a pointer to a function to be called when the object represented by <var>arg</var> is garbage-collected. At most one function finalizer can be set per function; if <var>arg</var> already has a finalizer, it is replaced by <var>fin</var>. </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Module-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Module-Functions.html</a> + </p> +</div> |