mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2025-01-08 15:35:02 +00:00
Document in the ELisp manual how to write loadable modules
* doc/lispref/internals.texi (Writing Dynamic Modules) (Module Initialization, Module Functions, Module Values) (Module Misc, Module Nonlocal): New nodes. * doc/lispref/loading.texi (Dynamic Modules): Add cross-reference to the new node. * doc/lispref/internals.texi (GNU Emacs Internals): * doc/lispref/elisp.texi (Top): Update menus for the new nodes.
This commit is contained in:
Eli Zaretskii
parent
a7ebc6bf63
commit
ce8b4584a3
@ -1588,9 +1588,18 @@ GNU Emacs Internals
|
||||
* Memory Usage:: Info about total size of Lisp objects made so far.
|
||||
* C Dialect:: What C variant Emacs is written in.
|
||||
* Writing Emacs Primitives:: Writing C code for Emacs.
|
||||
* Writing Dynamic Modules:: Writing loadable modules for Emacs.
|
||||
* Object Internals:: Data formats of buffers, windows, processes.
|
||||
* C Integer Types:: How C integer types are used inside Emacs.
|
||||
|
||||
Writing Dynamic Modules
|
||||
|
||||
* Module Initialization::
|
||||
* Module Functions::
|
||||
* Module Values::
|
||||
* Module Misc::
|
||||
* Module Nonlocal::
|
||||
|
||||
Object Internals
|
||||
|
||||
* Buffer Internals:: Components of a buffer structure.
|
||||
|
||||
@ -18,6 +18,7 @@ internal aspects of GNU Emacs that may be of interest to C programmers.
|
||||
* Memory Usage:: Info about total size of Lisp objects made so far.
|
||||
* C Dialect:: What C variant Emacs is written in.
|
||||
* Writing Emacs Primitives:: Writing C code for Emacs.
|
||||
* Writing Dynamic Modules:: Writing loadable modules for Emacs.
|
||||
* Object Internals:: Data formats of buffers, windows, processes.
|
||||
* C Integer Types:: How C integer types are used inside Emacs.
|
||||
@end menu
|
||||
@ -980,6 +981,708 @@ in @file{byte-opt.el} that binds @code{side-effect-free-fns} and
|
||||
@code{side-effect-and-error-free-fns} so that the compiler optimizer
|
||||
knows about it.
|
||||
|
||||
@node Writing Dynamic Modules
|
||||
@section Writing Dynamically-Loaded Modules
|
||||
@cindex writing emacs modules
|
||||
@cindex dynamic modules, writing
|
||||
|
||||
@cindex module @acronym{API}
|
||||
This section describes the Emacs module @acronym{API} and how to use
|
||||
it as part of writing extension modules for Emacs. The module
|
||||
@acronym{API} is defined in the C programming language, therefore the
|
||||
description and the examples in this section assume the module is
|
||||
written in C@. For other programming languages, you will need to use
|
||||
the appropriate bindings, interfaces and facilities for calling C code.
|
||||
Emacs C code requires a C99 or later compiler (@pxref{C Dialect}), and
|
||||
so the code examples in this section also follow that standard.
|
||||
|
||||
Writing a module and integrating it into Emacs comprises the following
|
||||
tasks:
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
Writing initialization code for the module.
|
||||
|
||||
@item
|
||||
Writing one or more module functions.
|
||||
|
||||
@item
|
||||
Communicating values and objects between Emacs and your module
|
||||
functions.
|
||||
|
||||
@item
|
||||
Handling of error conditions and nonlocal exits.
|
||||
@end itemize
|
||||
|
||||
@noindent
|
||||
The following subsections describe these tasks and the @acronym{API}
|
||||
itself in more detail.
|
||||
|
||||
Once your module is written, compile it to produce a shared library,
|
||||
according to the conventions of the underlying platform. Then place
|
||||
the shared library in a directory mentioned in @code{load-path}
|
||||
(@pxref{Library Search}), where Emacs will find it.
|
||||
|
||||
If you wish to verify the conformance of a modue to the Emacs dynamic
|
||||
module @acronym{API}, invoke Emacs with the @kbd{--module-assertions}
|
||||
option. @xref{Initial Options,,,emacs, The GNU Emacs Manual}.
|
||||
|
||||
@menu
|
||||
* Module Initialization::
|
||||
* Module Functions::
|
||||
* Module Values::
|
||||
* Module Misc::
|
||||
* Module Nonlocal::
|
||||
@end menu
|
||||
|
||||
@node Module Initialization
|
||||
@subsection Module Initialization Code
|
||||
@cindex module initialization
|
||||
|
||||
Begin your module by including the header file @file{emacs-module.h}
|
||||
and defining the GPL compatibility symbol:
|
||||
|
||||
@example
|
||||
#include <emacs-module.h>
|
||||
|
||||
int plugin_is_GPL_compatible;
|
||||
@end example
|
||||
|
||||
The @file{emacs-module.h} file is installed into your system's include
|
||||
tree as part of the Emacs installation. Alternatively, you can find
|
||||
it in the Emacs source tree.
|
||||
|
||||
@anchor{module initialization function}
|
||||
Next, write an initialization function for the module.
|
||||
|
||||
@deftypefn Function int emacs_module_init (struct emacs_runtime *@var{runtime})
|
||||
Emacs calls this function when it loads a module. If a module does
|
||||
not export a function named @code{emacs_module_init}, trying to load
|
||||
the module will signal an error. The initialization function should
|
||||
return zero if the initialization succeeds, non-zero otherwise. In
|
||||
the latter case, Emacs will signal an error, and the loading of the
|
||||
module will fail. If the user presses @kbd{C-g} during the
|
||||
initialization, Emacs ignores the return value of the initialization
|
||||
function and quits (@pxref{Quitting}). (If needed, you can catch user
|
||||
quitting inside the initialization function, @pxref{should_quit}.)
|
||||
|
||||
The argument @var{runtime} is a pointer to a C @code{struct} that
|
||||
includes 2 public fields: @code{size}, which provides the size of the
|
||||
structure in bytes; and @code{get_environment}, which provides a
|
||||
pointer to a function that allows the module initialization function
|
||||
access to the Emacs environment object and its interfaces.
|
||||
|
||||
The initialization function should perform whatever initialization is
|
||||
required for the module. In addition, it can perform the following
|
||||
tasks:
|
||||
|
||||
@table @asis
|
||||
@cindex compatibility, between modules and Emacs
|
||||
@item Compatibility verification
|
||||
A module can verify that the Emacs executable which loads the module
|
||||
is compatible with the module, by comparing the @code{size} member of
|
||||
the @var{runtime} structure with the value compiled into the module:
|
||||
|
||||
@example
|
||||
int
|
||||
emacs_module_init (struct emacs_runtime *ert)
|
||||
@{
|
||||
if (ert->size < sizeof (*ert))
|
||||
return 1;
|
||||
@}
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
If the size of the runtime object passed to the module is smaller than
|
||||
what it expects, it means the module was compiled for an Emacs version
|
||||
newer (later) than the one which attempts to load it, i.e.@: the
|
||||
module might be incompatible with the Emacs binary.
|
||||
|
||||
In addition, a module can verify the compatibility of the module
|
||||
@acronym{API} with what the module expects. The following sample code
|
||||
assumes it is part of the @code{emacs_module_init} function shown
|
||||
above:
|
||||
|
||||
@example
|
||||
emacs_env *env = ert->get_environment (ert);
|
||||
if (env->size < sizeof (*env))
|
||||
return 2;
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
@cindex module runtime environment
|
||||
This calls the @code{get_environment} function using the pointer
|
||||
provided in the @code{runtime} structure to retrieve a pointer to the
|
||||
@acronym{API}'s @dfn{environment}, a C @code{struct} which also has a
|
||||
@code{size} field holding the size of the structure in bytes.
|
||||
|
||||
Finally, you can write a module that will work with older versions of
|
||||
Emacs, by comparing the size of the environment passed by Emacs with
|
||||
known sizes, like this:
|
||||
|
||||
@example
|
||||
emacs_env *env = ert->get_environment (ert);
|
||||
if (env->size >= sizeof (struct emacs_env_26))
|
||||
emacs_version = 26; /* Emacs 26 or later. */
|
||||
else if (env->size >= sizeof (struct emacs_env_25))
|
||||
emacs_version = 25;
|
||||
else
|
||||
return 2; /* Unknown or unsupported version. */
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
This works because later Emacs versions always @emph{add} members to
|
||||
the environment, never @emph{remove} any members, so the size can only
|
||||
grow with new Emacs releases. Given the version of Emacs, the module
|
||||
can use only the parts of the module @acronym{API} that existed in
|
||||
that version, since those parts are identical in later versions.
|
||||
|
||||
We recommend that modules always perform the compatibility
|
||||
verification, unless they do their job entirely in the initialization
|
||||
function, and don't access any Lisp objects or use any Emacs functions
|
||||
accessible through the environment structure.
|
||||
|
||||
@item Binding module functions to Lisp symbols
|
||||
This gives the module functions names so that Lisp code could call it
|
||||
by that name. We describe how to do this in @ref{Module Functions}
|
||||
below.
|
||||
@end table
|
||||
@end deftypefn
|
||||
|
||||
@node Module Functions
|
||||
@subsection Writing Module Functions
|
||||
@cindex writing module functions
|
||||
@cindex module functions
|
||||
|
||||
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 @dfn{module functions}.
|
||||
|
||||
A module function has the following general form and signature:
|
||||
|
||||
@deftypefn Function emacs_value module_func (emacs_env *@var{env}, ptrdiff_t @var{nargs}, emacs_value *@var{args}, void *@var{data})
|
||||
The @var{env} argument provides a pointer to the @acronym{API}
|
||||
environment, needed to access Emacs objects and functions. The
|
||||
@var{nargs} argument is the required number of arguments, which can be
|
||||
zero (see @code{make_function} below for more flexible specification
|
||||
of the argument number), and @var{args} is a pointer to the array of
|
||||
the function arguments. The argument @var{data} points to additional
|
||||
data required by the function, which was arranged when
|
||||
@code{make_function} (see below) was called to create an Emacs
|
||||
function from @code{module_func}.
|
||||
|
||||
Module functions use the type @code{emacs_value} to communicate Lisp
|
||||
objects between Emacs and the module (@pxref{Module Values}). The
|
||||
@acronym{API}, described below and in the following subsections,
|
||||
provides facilities for conversion between basic C data types and the
|
||||
corresponding @code{emacs_value} objects.
|
||||
|
||||
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} value the function returned.
|
||||
However, if the user typed @kbd{C-g}, or if the module function or its
|
||||
callees signaled an error or exited nonlocally (@pxref{Module
|
||||
Nonlocal}), Emacs will ignore the returned value and quit or throw as
|
||||
it does when Lisp code encounters the same situations.
|
||||
@end deftypefn
|
||||
|
||||
After writing your C code for a module function, you should make a
|
||||
Lisp function object from it using @code{make_function}. This is
|
||||
normally done in the module initialization function (@pxref{module
|
||||
initialization function}), after verifying the @acronym{API}
|
||||
compatibility, and uses the pointer to @code{make_function} provided
|
||||
in the environment (recall that the pointer to the environment is
|
||||
returned by @code{get_environment}).
|
||||
|
||||
@deftypefn Function emacs_value make_function (emacs_env *@var{env}, ptrdiff_t @var{min_arity}, ptrdiff_t @var{max_arity}, subr @var{func}, const char *@var{docstring}, void *@var{data})
|
||||
@vindex emacs_variadic_function
|
||||
This returns an Emacs function created from the C function @var{func},
|
||||
whose signature is as described for @code{module_func} above (assumed
|
||||
here to be @code{typedef}'ed as @code{subr}). The arguments
|
||||
@var{min_arity} and @var{max_arity} specify the minimum and maximum
|
||||
number of arguments that @var{func} can accept. The @var{max_arity}
|
||||
argument can have the special value @code{emacs_variadic_function},
|
||||
which makes the function accept an unlimited number of arguments, like
|
||||
the @code{&rest} keyword in Lisp (@pxref{Argument List}).
|
||||
|
||||
The argument @var{data} is a way to arrange for arbitrary additional
|
||||
data to be passed to @var{func} when it is called. Whatever pointer
|
||||
is passed to @code{make_function} will be passed unaltered to
|
||||
@var{func}.
|
||||
|
||||
The argument @var{docstring} specifies the documentation string for
|
||||
the function. It should be either an @acronym{ASCII} string, or a
|
||||
UTF-8 encoded non-@acronym{ASCII} string, or a @code{NULL} 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 @ref{Function Documentation}.
|
||||
|
||||
Since every module function must accept the pointer to the environment
|
||||
as its first argument, the call to @code{make_function} 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.
|
||||
@end deftypefn
|
||||
|
||||
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} function @code{intern} (@pxref{intern}) whose pointer is
|
||||
also provided in the environment that module functions can access.
|
||||
|
||||
Combining the above steps, code that arranges for a C function
|
||||
@code{module_func} to be callable as @code{module-func} from Lisp will
|
||||
look like this, as part of the module initialization function:
|
||||
|
||||
@example
|
||||
emacs_env *env = ert->get_environment (ert);
|
||||
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);
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
This makes the symbol @code{module-func} known to Emacs by calling
|
||||
@code{env->intern}, then invokes @code{defalias} from Emacs to bind
|
||||
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}.
|
||||
|
||||
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
|
||||
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} defined as above, one way of making an
|
||||
interactive command @code{module-cmd} based on it is with the
|
||||
following simple Lisp wrapper:
|
||||
|
||||
@lisp
|
||||
(defun module-cmd (&rest args)
|
||||
"Documentation string for the command."
|
||||
(interactive @var{spec})
|
||||
(apply 'module-func args))
|
||||
@end lisp
|
||||
|
||||
The Lisp package which goes with your module could then load the
|
||||
module using the @code{module-load} primitive (@pxref{Dynamic
|
||||
Modules}) when the package is loaded into Emacs.
|
||||
|
||||
@node Module Values
|
||||
@subsection Conversion Between Lisp and Module Values
|
||||
@cindex module values, conversion
|
||||
|
||||
@cindex @code{emacs_value} data type
|
||||
With very few exceptions, most modules need to exchange data with
|
||||
Lisp programs that call them: accept arguments to module functions and
|
||||
return values from module functions. For this purpose, the module
|
||||
@acronym{API} provides the @code{emacs_value} type, which represents
|
||||
Emacs Lisp objects communicated via the @acronym{API}; it is the
|
||||
functional equivalent of the @code{Lisp_Object} type used in Emacs C
|
||||
primitives (@pxref{Writing Emacs Primitives}). This section describes
|
||||
the parts of the module @acronym{API} that allow to create
|
||||
@code{emacs_value} objects corresponding to basic Lisp data types, and
|
||||
how to access from C data in @code{emacs_value} objects that
|
||||
correspond to Lisp objects.
|
||||
|
||||
All of the functions described below are actually @emph{function
|
||||
pointers} provided via the pointer to the environment which every
|
||||
module function accepts. Therefore, module code should call these
|
||||
functions through the environment pointer, like this:
|
||||
|
||||
@example
|
||||
emacs_env *env; /* the environment pointer */
|
||||
env->some_function (arguments@dots{});
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
The @code{emacs_env} pointer will usually come from the first argument
|
||||
to the module function, or from the call to @code{get_environment} if
|
||||
you need the environment in the module initialization function.
|
||||
|
||||
Most of the functions described below became available in Emacs 25,
|
||||
the first Emacs release that supported dynamic modules. For the few
|
||||
functions that became available in later Emacs releases, we mention
|
||||
the first Emacs version that supported them.
|
||||
|
||||
The following @acronym{API} functions extract values of various C data
|
||||
types from @code{emacs_value} objects. They all raise the
|
||||
@code{wrong-type-argument} error condition (@pxref{Type Predicates})
|
||||
if the argument @code{emacs_value} object is not of the type expected
|
||||
by the function. @xref{Module Nonlocal}, for details of how signaling
|
||||
errors works in Emacs modules, and how to catch error conditions
|
||||
inside the module before they are reported to Emacs. The
|
||||
@acronym{API} function @code{type_of} (@pxref{Module Misc, type_of})
|
||||
can be used to obtain the type of a @code{emacs_value} object.
|
||||
|
||||
@deftypefn Function intmax_t extract_integer (emacs_env *@var{env}, emacs_value @var{arg})
|
||||
This function returns the value of a Lisp integer specified by
|
||||
@var{arg}. The C data type of the return value, @code{intmax_t}, is
|
||||
the widest integral data type supported by the C compiler, typically
|
||||
@w{@code{long long}}.
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function double extract_float (emacs_env *@var{env}, emacs_value @var{arg})
|
||||
This function returns the value of a Lisp float specified by
|
||||
@var{arg}, as a C @code{double} value.
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function bool copy_string_contents (emacs_env *@var{env}, emacs_value @var{arg}, char *@var{buf}, ptrdiff_t *@var{len})
|
||||
This function stores the UTF-8 encoded text of a Lisp string specified
|
||||
by @var{arg} in the array of @code{char} pointed by @var{buf}, which
|
||||
should have enough space to hold at least @code{*@var{len}} bytes,
|
||||
including the terminating null byte. The argument @var{len} must not
|
||||
be a @code{NULL} pointer, and, when the function is called, it should
|
||||
point to a value that specifies the size of @var{buf} in bytes.
|
||||
|
||||
If the buffer size specified by @code{*@var{len}} is large enough to
|
||||
hold the string's text, the function stores in @code{*@var{len}} the
|
||||
actual number of bytes copied to @var{buf}, including the terminating
|
||||
null byte, and returns @code{true}. If the buffer is too small, the
|
||||
function raises the @code{args-out-of-range} error condition, stores
|
||||
the required number of bytes in @code{*@var{len}}, and returns
|
||||
@code{false}. @xref{Module Nonlocal}, for how to handle pending error
|
||||
conditions.
|
||||
|
||||
The argument @var{buf} can be a @code{NULL} pointer, in which case the
|
||||
function stores in @code{*@var{len}} the number of bytes required for
|
||||
storing the contents of @var{arg}, and returns @code{true}. This is
|
||||
how you can determine the size of @var{buf} needed to store a
|
||||
particular string: first call @code{copy_string_contents} with
|
||||
@code{NULL} as @var{buf}, then allocate enough memory to hold the
|
||||
number of bytes stored by the function in @code{*@var{len}}, and call
|
||||
the function again with non-@code{NULL} @var{buf} to actually perform
|
||||
the text copying.
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function emacs_value vec_get (emacs_env *@var{env}, emacs_value @var{vector}, ptrdiff_t @var{index})
|
||||
This function returns the element of @var{vector} at @var{index}. The
|
||||
@var{index} of the first vector element is zero. The function raises
|
||||
the @code{args-out-of-range} error condition if the value of
|
||||
@var{index} is invalid. To extract C data from the value the function
|
||||
returns, use the other extraction functions described here, as
|
||||
appropriate for the Lisp data type stored in that element of the
|
||||
vector.
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function ptrdiff_t vec_size (emacs_env *@var{env}, emacs_value @var{vector})
|
||||
This function returns the number of elements in @var{vector}.
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function void vec_set (emacs_env *@var{env}, emacs_value @var{vector}, ptrdiff_t @var{index}, emacs_value @var{value})
|
||||
This function stores @var{value} in the element of @var{vector} whose
|
||||
index is @var{index}. It raises the @code{args-out-of-range} error
|
||||
condition if the value of @var{index} is invalid.
|
||||
@end deftypefn
|
||||
|
||||
The following @acronym{API} functions create @code{emacs_value}
|
||||
objects from basic C data types. They all return the created
|
||||
@code{emacs_value} object.
|
||||
|
||||
@deftypefn Function emacs_value make_integer (emacs_env *@var{env}, intmax_t @var{n})
|
||||
This function takes an integer argument @var{n} and returns the
|
||||
corresponding @code{emacs_value} object. It raises the
|
||||
@code{overflow-error} error condition if the value of @var{n} cannot
|
||||
be represented as an Emacs integer, i.e.@: is not inside the limits
|
||||
set by @code{most-negative-fixnum} and @code{most-positive-fixnum}
|
||||
(@pxref{Integer Basics}).
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function emacs_value make_float (emacs_env *@var{env}, double @var{d})
|
||||
This function takes a @code{double} argument @var{d} and returns the
|
||||
corresponding Emacs floating-point value.
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function emacs_value make_string (emacs_env *@var{env}, const char *@var{str}, ptrdiff_t @var{strlen})
|
||||
This function creates an Emacs string from C text string pointed by
|
||||
@var{str} whose length in bytes, not including the terminating null
|
||||
byte, is @var{strlen}. The original string in @var{str} can be either
|
||||
an @acronym{ASCII} string or a UTF-8 encoded non-@acronym{ASCII}
|
||||
string; it can include embedded null bytes, and doesn't have to end in
|
||||
a terminating null byte at @code{@var{str}[@var{strlen}]}. The
|
||||
function raises the @code{overflow-error} error condition if
|
||||
@var{strlen} is negative or exceeds the maximum length of an Emacs
|
||||
string.
|
||||
@end deftypefn
|
||||
|
||||
The @acronym{API} does not provide functions to manipulate Lisp data
|
||||
structures, for example, create lists with @code{cons} and @code{list}
|
||||
(@pxref{Building Lists}), extract list members with @code{car} and
|
||||
@code{cdr} (@pxref{List Elements}), create vectors with @code{vector}
|
||||
(@pxref{Vector Functions}), etc. For these, use @code{intern} and
|
||||
@code{funcall}, described in the next subsection, to call the
|
||||
corresponding Lisp functions.
|
||||
|
||||
Normally, @code{emacs_value} objects have a rather short lifetime: it
|
||||
ends when the @code{emacs_env} pointer used for their creation goes
|
||||
out of scope. Occasionally, you may need to create @dfn{global
|
||||
references}: @code{emacs_value} objects that live as long as you
|
||||
wish. Use the following two functions to manage such objects.
|
||||
|
||||
@deftypefn Function emacs_value make_global_ref (emacs_env *@var{env}, emacs_value @var{value})
|
||||
This function returns a global reference for @var{value}.
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function void free_global_ref (emacs_env *@var{env}, emacs_value @var{global_value})
|
||||
This function frees the @var{global_value} previously created by
|
||||
@code{make_global_ref}. The @var{global_value} is no longer valid
|
||||
after the call. Your module code should pair each call to
|
||||
@code{make_global_ref} with the corresponding @code{free_global_ref}.
|
||||
@end deftypefn
|
||||
|
||||
@cindex user pointer, using in module functions
|
||||
An alternative to keeping around C data structures that need to be
|
||||
passed to module functions later is to create @dfn{user pointer}
|
||||
objects. A user pointer, or @code{user-ptr}, object is a Lisp object
|
||||
that encapsulates a C pointer and can have an associated finalizer
|
||||
function, which is called when the object is garbage-collected
|
||||
(@pxref{Garbage Collection}). The module @acronym{API} provides
|
||||
functions to create and access @code{user-ptr} objects. These
|
||||
functions raise the @code{wrong-type-argument} error condition if they
|
||||
are called on @code{emacs_value} that doesn't represent a
|
||||
@code{user-ptr} object.
|
||||
|
||||
@deftypefn Function emacs_value make_user_ptr (emacs_env *@var{env}, emacs_finalizer @var{fin}, void *@var{ptr})
|
||||
This function creates and returns a @code{user-ptr} object which wraps
|
||||
the C pointer @var{ptr}. The finalizer function @var{fin} can be a
|
||||
@code{NULL} pointer (meaning no finalizer), or it can be a function of
|
||||
the following signature:
|
||||
|
||||
@example
|
||||
typedef void (*emacs_finalizer) (void *@var{ptr});
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
If @var{fin} is not a @code{NULL} pointer, it will be called with the
|
||||
@var{ptr} as the argument when the @code{user-ptr} object is
|
||||
garbage-collected. Don't run any expensive code in a finalizer,
|
||||
because GC must finish quickly to keep Emacs responsive.
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function void *get_user_ptr (emacs_env *@var{env}, emacs_value val)
|
||||
This function extracts the C pointer from the Lisp object represented
|
||||
by @var{val}.
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function void set_user_ptr (emacs_env *@var{env}, emacs_value @var{value}, void *@var{ptr})
|
||||
This function sets the C pointer embedded in the @code{user-ptr}
|
||||
object represented by @var{value} to @var{ptr}.
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function emacs_finalizer get_user_finalizer (emacs_env *@var{env}, emacs_value val)
|
||||
This function returns the finalizer of the @code{user-ptr} object
|
||||
represented by @var{val}, or @code{NULL} if it doesn't have a finalizer.
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function void set_user_finalizer (emacs_env *@var{env}, emacs_value @var{val}, emacs_finalizer @var{fin})
|
||||
This function changes the finalizer of the @code{user-ptr} object
|
||||
represented by @var{val} to be @var{fin}. If @var{fin} is a
|
||||
@code{NULL} pointer, the @code{user-ptr} object will have no finalizer.
|
||||
@end deftypefn
|
||||
|
||||
@node Module Misc
|
||||
@subsection Miscellaneous Convenience Functions for Modules
|
||||
|
||||
This subsection describes a few convenience functions provided by
|
||||
the module @acronym{API}. Like the functions described in previous
|
||||
subsections, all of them are actually function pointers, and need to
|
||||
be called via the @code{emacs_env} pointer. Description of functions
|
||||
that were introduced after Emacs 25 calls out the first version where
|
||||
they became available.
|
||||
|
||||
@deftypefn Function bool eq (emacs_env *@var{env}, emacs_value @var{val1}, emacs_value @var{val2})
|
||||
This function returns @code{true} if the Lisp objects represented by
|
||||
@var{val1} and @var{val2} are identical, @code{false} otherwise. This
|
||||
is the same as the Lisp function @code{eq} (@pxref{Equality
|
||||
Predicates}), but avoids the need to intern the objects represented by
|
||||
the arguments.
|
||||
|
||||
There are no @acronym{API} functions for other equality predicates, so
|
||||
you will need to use @code{intern} and @code{funcall}, described
|
||||
below, to perform more complex equality tests.
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function bool is_not_nil (emacs_env *@var{env}, emacs_value @var{val})
|
||||
This function tests whether the Lisp object represented by @var{val}
|
||||
is non-@code{nil}; it returns @code{true} or @code{false} accordingly.
|
||||
|
||||
Note that you could implement an equivalent test by using
|
||||
@code{intern} to get an @code{emacs_value} representing @code{nil},
|
||||
then use @code{eq}, described above, to test for equality. But using
|
||||
this function is more convenient.
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function emacs_value type_of (emacs_env *@var{env}, emacs_value @code{object})
|
||||
This function returns the type of @var{object} as a value that
|
||||
represents a symbol: @code{string} for a string, @code{integer} for an
|
||||
integer, @code{process} for a process, etc. @xref{Type Predicates}.
|
||||
You can use @code{intern} and @code{eq} to compare against known type
|
||||
symbols, if your code needs to depend on the object type.
|
||||
@end deftypefn
|
||||
|
||||
@anchor{intern}
|
||||
@deftypefn Function emacs_value intern (emacs_env *@var{env}, const char *name)
|
||||
This function returns an interned Emacs symbol whose name is
|
||||
@var{name}, which should be an @acronym{ASCII} null-terminated string.
|
||||
It creates a new symbol if one does not already exist.
|
||||
|
||||
Together with @code{funcall}, described below, this function provides
|
||||
a means for invoking any Lisp-callable Emacs function, provided that
|
||||
its name is a pure @acronym{ASCII} string. For example, here's how to
|
||||
intern a symbol whose name @code{name_str} is non-@acronym{ASCII}, by
|
||||
calling the more powerful Emacs @code{intern} function
|
||||
(@pxref{Creating Symbols}):
|
||||
|
||||
@example
|
||||
emacs_value fintern = env->intern (env, "intern");
|
||||
emacs_value sym_name =
|
||||
env->make_string (env, name_str, strlen (name_str));
|
||||
emacs_value intern_args[] = @{ sym_name, env->intern (env, "nil") @};
|
||||
emacs_value symbol = env->funcall (env, fintern, 2, intern_args);
|
||||
@end example
|
||||
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function emacs_value funcall (emacs_env *@var{env}, emacs_value @var{func}, ptrdiff_t @var{nargs}, emacs_value *@var{args})
|
||||
This function calls the specified @var{func} passing it @var{nargs}
|
||||
arguments from the array pointed to by @var{args}. The argument
|
||||
@var{func} can be a function symbol (e.g., returned by @code{intern}
|
||||
described above), a module function returned by @code{make_function}
|
||||
(@pxref{Module Functions}), a subroutine written in C, etc. If
|
||||
@var{nargs} is zero, @var{args} can be a @code{NULL} pointer.
|
||||
|
||||
The function returns the value that @var{func} returned.
|
||||
@end deftypefn
|
||||
|
||||
If your module includes potentially long-running code, it is a good
|
||||
idea to check from time to time in that code whether the user wants to
|
||||
quit, e.g., by typing @kbd{C-g} (@pxref{Quitting}). The following
|
||||
function, which is available since Emacs 26.1, is provided for that
|
||||
purpose.
|
||||
|
||||
@anchor{should_quit}
|
||||
@deftypefn Function bool should_quit (emacs_env *@var{env})
|
||||
This function returns @code{true} if the user wants to quit. In that
|
||||
case, we recommend that your module function aborts any on-going
|
||||
processing and returns as soon as possible.
|
||||
@end deftypefn
|
||||
|
||||
@node Module Nonlocal
|
||||
@subsection Nonlocal Exits in Modules
|
||||
@cindex nonlocal exits, in modules
|
||||
|
||||
Emacs Lisp supports nonlocal exits, whereby program control is
|
||||
transfered from one point in a program to another remote point.
|
||||
@xref{Nonlocal Exits}. Thus, Lisp functions called by your module
|
||||
might exit nonlocally by calling @code{signal} or @code{throw}, and
|
||||
your module functions must handle such nonlocal exits properly. Such
|
||||
handling is needed because C programs will not automatically release
|
||||
resources and perform other cleanups in these cases; your module code
|
||||
must itself do it. The module @acronym{API} provides facilities for
|
||||
that, described in this subsection. They are generally available
|
||||
since Emacs 25; those of them that became available in later releases
|
||||
explicitly call out the first Emacs version where they became part of
|
||||
the @acronym{API}.
|
||||
|
||||
When some Lisp code called by a module function signals an error or
|
||||
throws, the nonlocal exit is trapped, and the pending exit and its
|
||||
associated data are stored in the environment. Whenever a nonlocal
|
||||
exit is pending in the environment, any module @acronym{API} function
|
||||
called with a pointer to that environment will return immediately
|
||||
without any processing (the functions @code{non_local_exit_check},
|
||||
@code{non_local_exit_get}, and @code{non_local_exit_clear} are
|
||||
exceptions from this rule). If your module function then does nothing
|
||||
and returns to Emacs, a pending nonlocal exit will cause Emacs to act
|
||||
on it: signal an error or throw to the corresponding @code{catch}.
|
||||
|
||||
So the simplest ``handling'' of nonlocal exits in module functions is
|
||||
to do nothing special and let the rest of your code to run as if
|
||||
nothing happened. However, this can cause two classes of problems:
|
||||
|
||||
@itemize @minus
|
||||
@item
|
||||
Your module function might use uninitialized or undefined values,
|
||||
since @acronym{API} functions return immediately without producing the
|
||||
expected results.
|
||||
|
||||
@item
|
||||
Your module might leak resources, because it might not have the
|
||||
opportunity to release them.
|
||||
@end itemize
|
||||
|
||||
Therefore, we recommend that your module functions check for nonlocal
|
||||
exit conditions and recover from them, using the functions described
|
||||
below.
|
||||
|
||||
@deftypefn Function enum emacs_funcall_exit non_local_exit_check (emacs_env *@var{env})
|
||||
This function returns the kind of nonlocal exit condition stored in
|
||||
@var{env}. The possible values are:
|
||||
|
||||
@vindex emacs_funcall_exit@r{, enumeration}
|
||||
@vtable @code
|
||||
@item emacs_funcall_exit_return
|
||||
The last @acronym{API} function exited normally.
|
||||
@item emacs_funcall_exit_signal
|
||||
The last @acronym{API} function signaled an error.
|
||||
@item emacs_funcall_exit_throw
|
||||
The last @acronym{API} function exited via @code{throw}.
|
||||
@end vtable
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function emacs_funcall_exit non_local_exit_get (emacs_env *@var{env}, emacs_value *@var{symbol}, emacs_value *@var{data})
|
||||
This function returns the kind of nonlocal exit condition stored in
|
||||
@var{env}, like @code{non_local_exit_check} does, but it also returns
|
||||
the full information about the nonlocal exit, if any. If the return
|
||||
value is @code{emacs_funcall_exit_signal}, the function stores the
|
||||
error symbol in @code{*@var{symbol}} and the error data in
|
||||
@code{*@var{data}} (@pxref{Signaling Errors}). If the return value is
|
||||
@code{emacs_funcall_exit_throw}, the function stores the @code{catch}
|
||||
tag symbol in @code{*@var{symbol}} and the @code{throw} value in
|
||||
@code{*@var{data}}. The function doesn't store anything in memory
|
||||
pointed by these arguments when the return value is
|
||||
@code{emacs_funcall_exit_return}.
|
||||
@end deftypefn
|
||||
|
||||
You should check nonlocal exit conditions where it matters: before you
|
||||
allocated some resource or after you allocated a resource that might
|
||||
need freeing, or where a failure means further processing is
|
||||
impossible or infeasible.
|
||||
|
||||
Once your module function detected that a nonlocal exit is pending, it
|
||||
can either return to Emacs (after performing the necessary local
|
||||
cleanup), or it can attempt to recover from the nonlocal exit. The
|
||||
following @acronym{API} functions will help with these tasks.
|
||||
|
||||
@deftypefn Function void non_local_exit_clear (emacs_env *@var{env})
|
||||
This function clears the pending nonlocal exit conditions and data
|
||||
from @var{env}. After calling it, the module @acronym{API} functions
|
||||
will work normally. Use this function if your module function can
|
||||
recover from nonlocal exits of the Lisp functions it calls and
|
||||
continue, and also before calling any of the following two functions
|
||||
(or any other @acronym{API} functions, if you want them to perform
|
||||
their intended processing when a nonlocal exit is pending).
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function void non_local_exit_throw (emacs_env *@var{env}, emacs_value @var{tag}, emacs_value @var{value})
|
||||
This function throws to the Lisp @code{catch} symbol represented by
|
||||
@var{tag}, passing it @var{value} as the value to return. Your module
|
||||
function should in general return soon after calling this function.
|
||||
One use of this function is when you want to re-throw a non-local exit
|
||||
from one of the called @acronym{API} or Lisp functions.
|
||||
@end deftypefn
|
||||
|
||||
@deftypefn Function void non_local_exit_signal (emacs_env *@var{env}, emacs_value @var{error}, emacs_value @var{data})
|
||||
This function signals the error represented by @var{error} with the
|
||||
specified error data @var{data}. The module function should return
|
||||
soon after calling this function. This function could be useful,
|
||||
e.g., for signaling errors from module functions to Emacs.
|
||||
@end deftypefn
|
||||
|
||||
|
||||
@node Object Internals
|
||||
@section Object Internals
|
||||
@cindex object internals
|
||||
|
||||
@ -1139,8 +1139,6 @@ Features}).
|
||||
@section Emacs Dynamic Modules
|
||||
@cindex dynamic modules
|
||||
|
||||
@c FIXME: This is intentionally incomplete, as the module integration
|
||||
@c is not yet finished. To be refined later.
|
||||
A @dfn{dynamic Emacs module} is a shared library that provides
|
||||
additional functionality for use in Emacs Lisp programs, just like a
|
||||
package written in Emacs Lisp would.
|
||||
@ -1162,30 +1160,43 @@ Every dynamic module should export a C-callable function named
|
||||
@code{load} or @code{require} which loads the module. It should also
|
||||
export a symbol named @code{plugin_is_GPL_compatible} to indicate that
|
||||
its code is released under the GPL or compatible license; Emacs will
|
||||
refuse to load modules that don't export such a symbol.
|
||||
signal an error if your program tries to load modules that don't
|
||||
export such a symbol.
|
||||
|
||||
If a module needs to call Emacs functions, it should do so through the
|
||||
API defined and documented in the header file @file{emacs-module.h}
|
||||
that is part of the Emacs distribution.
|
||||
@acronym{API} (Application Programming Interface) defined and
|
||||
documented in the header file @file{emacs-module.h} that is part of
|
||||
the Emacs distribution. @xref{Writing Dynamic Modules}, for details
|
||||
of using that API when writing your own modules.
|
||||
|
||||
@cindex user-ptr object
|
||||
@cindex user pointer object
|
||||
Modules can create @code{user-ptr} Lisp objects that embed pointers to
|
||||
C struct's defined by the module. This is useful for keeping around
|
||||
complex data structures created by a module, to be passed back to the
|
||||
module's functions. User-ptr objects can also have associated
|
||||
@dfn{finalizers} -- functions to be run when the object is GC'ed; this
|
||||
is useful for freeing any resources allocated for the underlying data
|
||||
structure, such as memory, open file descriptors, etc.
|
||||
structure, such as memory, open file descriptors, etc. @xref{Module
|
||||
Values}.
|
||||
|
||||
@defun user-ptrp object
|
||||
This function returns @code{t} if its argument is a @code{user-ptr}
|
||||
object.
|
||||
@end defun
|
||||
|
||||
@defun module-load file
|
||||
Emacs calls this low-level primitive to load a module from the
|
||||
specified @var{file} and perform the necessary initialization of the
|
||||
module. This is the primitive which makes sure the module exports the
|
||||
@code{plugin_is_GPL_compatible} symbol, calls the module's
|
||||
@code{emacs_module_init} function, and signals an error if that
|
||||
function returns an error indication, or if the use typed @kbd{C-g}
|
||||
during the initialization. If the initialization succeeds,
|
||||
@code{module-load} returns @code{t}. Note that @var{file} must
|
||||
already have the proper file-name extension, as this function doesn't
|
||||
try looking for files with known extensions, unlike @code{load}.
|
||||
@end defun
|
||||
|
||||
Loadable modules in Emacs are enabled by using the
|
||||
@kbd{--with-modules} option at configure time.
|
||||
|
||||
If you write your own dynamic modules, you may wish to verify their
|
||||
conformance to the Emacs dynamic module API. Invoking Emacs with the
|
||||
@kbd{--module-assertions} option will help you in this matter.
|
||||
@xref{Initial Options,,,emacs, The GNU Emacs Manual}.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user