master 719ad59 1/2: Promote function type aliases to the public module API.

[Philipp Stephani]

branch: master
commit 719ad593872b606d2ca6ca5a144e37251c378078
Author: Philipp Stephani <address@hidden>
Commit: Philipp Stephani <address@hidden>

    Promote function type aliases to the public module API.
    
    Previously module authors had to define type aliases for module
    functions and finalizers themselves.  This commit adds and documents
    aliases so that this is no longer necessary.
    
    * src/emacs-module.h.in: Add 'emacs_function' and 'emacs_finalizer'
    type aliases.
    
    * src/emacs-module.c: Remove old 'emacs_subr' and 'emacs_finalizer'
    type aliases.
    (struct Lisp_Module_Function, module_make_function): Switch from
    'emacs_subr' to 'emacs_function'.
    
    * doc/lispref/internals.texi (Module Functions): Document and use
    'emacs_function' type alias.
    (Module Values): Document 'emacs_finalizer' type alias.
    
    * etc/NEWS: Mention change.
---
 doc/lispref/internals.texi | 21 ++++++++++++++++-----
 etc/NEWS                   |  4 ++++
 src/emacs-module.c         | 14 ++------------
 src/emacs-module.h.in      | 15 +++++++++++++++
 4 files changed, 37 insertions(+), 17 deletions(-)

diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index cf66302..02180c7 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -1314,7 +1314,8 @@ 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})
+@deftypefn Function emacs_value emacs_function (emacs_env *@var{env}, 
ptrdiff_t @var{nargs}, emacs_value *@var{args}, void *@var{data})
+@tindex emacs_function
 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
@@ -1323,7 +1324,7 @@ 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}.
+function from @code{emacs_function}.
 
 Module functions use the type @code{emacs_value} to communicate Lisp
 objects between Emacs and the module (@pxref{Module Values}).  The
@@ -1338,6 +1339,10 @@ 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.
+
+The header @file{emacs-module.h} provides the type
+@code{emacs_function} as an alias type for a function pointer to a
+module function.
 @end deftypefn
 
 After writing your C code for a module function, you should make a
@@ -1348,11 +1353,11 @@ normally done in the module initialization function 
(@pxref{module
 initialization function}), after verifying the @acronym{API}
 compatibility.
 
-@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})
+@deftypefn Function emacs_value make_function (emacs_env *@var{env}, ptrdiff_t 
@var{min_arity}, ptrdiff_t @var{max_arity}, emacs_function @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
+whose signature is as described for @code{emacs_function} above.
+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},
@@ -1844,6 +1849,12 @@ represented by @var{arg} to be @var{fin}.  If @var{fin} 
is a
 finalizer.
 @end deftypefn
 
+@deftypefun void emacs_finalizer (void *@var{ptr})
+The header @file{emacs-module.h} provides the type
+@code{emacs_finalizer} as a type alias for an Emacs finalizer
+function.
+@end deftypefun
+
 @node Module Misc
 @subsection Miscellaneous Convenience Functions for Modules
 
diff --git a/etc/NEWS b/etc/NEWS
index a1c5792..5bd45d7 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -45,6 +45,10 @@ applies, and please also update docstrings as needed.
 
 * Lisp Changes in Emacs 28.1
 
+** The module header 'emacs-module.h' now contains type aliases
+'emacs_function' and 'emacs_finalizer' for module functions and
+finalizers, respectively.
+
 
 * Changes in Emacs 28.1 on Non-Free Operating Systems
 
diff --git a/src/emacs-module.c b/src/emacs-module.c
index ff1a054..7622913 100644
--- a/src/emacs-module.c
+++ b/src/emacs-module.c
@@ -122,12 +122,6 @@ To add a new module function, proceed as follows:
 /* Function prototype for the module init function.  */
 typedef int (*emacs_init_function) (struct emacs_runtime *);
 
-/* Function prototype for module user-pointer finalizers.  These
-   should not throw C++ exceptions, so emacs-module.h declares the
-   corresponding interfaces with EMACS_NOEXCEPT.  There is only C code
-   in this module, though, so this constraint is not enforced here.  */
-typedef void (*emacs_finalizer) (void *);
-
 
 /* Memory management.  */
 
@@ -466,10 +460,6 @@ module_non_local_exit_throw (emacs_env *env, emacs_value 
tag, emacs_value value)
                                   value_to_lisp (value));
 }
 
-/* Function prototype for the module Lisp functions.  */
-typedef emacs_value (*emacs_subr) (emacs_env *, ptrdiff_t,
-                                  emacs_value *, void *);
-
 /* Module function.  */
 
 /* A function environment is an auxiliary structure returned by
@@ -486,7 +476,7 @@ struct Lisp_Module_Function
 
   /* Fields ignored by GC.  */
   ptrdiff_t min_arity, max_arity;
-  emacs_subr subr;
+  emacs_function subr;
   void *data;
 } GCALIGNED_STRUCT;
 
@@ -505,7 +495,7 @@ allocate_module_function (void)
 
 static emacs_value
 module_make_function (emacs_env *env, ptrdiff_t min_arity, ptrdiff_t max_arity,
-                     emacs_subr func, const char *docstring, void *data)
+                     emacs_function func, const char *docstring, void *data)
 {
   MODULE_FUNCTION_BEGIN (NULL);
 
diff --git a/src/emacs-module.h.in b/src/emacs-module.h.in
index ecbfe28..fbeaebd 100644
--- a/src/emacs-module.h.in
+++ b/src/emacs-module.h.in
@@ -78,6 +78,21 @@ struct emacs_runtime
     EMACS_ATTRIBUTE_NONNULL(1);
 };
 
+/* Type aliases for function pointer types used in the module API.
+   Note that we don't use these aliases directly in the API to be able
+   to mark the function arguments as 'noexcept' before C++20.
+   However, users can use them if they want.  */
+
+/* Function prototype for the module Lisp functions.  These must not
+   throw C++ exceptions.  */
+typedef emacs_value (*emacs_function) (emacs_env *env, ptrdiff_t nargs,
+                                       emacs_value *args,
+                                       void *data)
+  EMACS_NOEXCEPT EMACS_ATTRIBUTE_NONNULL (1);
+
+/* Function prototype for module user-pointer finalizers.  These must
+   not throw C++ exceptions.  */
+typedef void (*emacs_finalizer) (void *data) EMACS_NOEXCEPT;
 
 /* Possible Emacs function call outcomes.  */
 enum emacs_funcall_exit