Add a module function to open a file descriptor connected to a pipe.

A common complaint about the module API is that modules can't
communicate asynchronously with Emacs.  While it isn't possible to
call arbitrary Emacs functions asynchronously, writing to a pipe
should always be fine and is a pretty low-hanging fruit.

This patch implements a function that adapts an existing pipe
process.  That way, users can use familiar tools like process filters
or 'accept-process-output'.

* src/module-env-28.h: Add 'open_channel' module function.

* src/emacs-module.c (module_open_channel): Provide definition for
'open_channel'.
(initialize_environment): Use it.

* src/process.c (open_channel_for_module): New helper function.
(syms_of_process): Define necessary symbol.

* test/src/emacs-module-tests.el (module/async-pipe): New unit test.

* test/data/emacs-module/mod-test.c (signal_system_error): New helper
function.
(signal_errno): Use it.
(write_to_pipe): New function running in the background.
(Fmod_test_async_pipe): New test module function.
(emacs_module_init): Export it.

* doc/lispref/internals.texi (Module Misc): Document new module
function.

* doc/lispref/processes.texi (Asynchronous Processes): New anchor
for pipe processes.

* etc/NEWS: Document 'open_channel' function.

1 files changed, 14 insertions, 0 deletions

diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 442f6d156b6..0c24dac7775 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -2022,6 +2022,20 @@ variable values and buffer content may have been modified in arbitrary
 ways.
 @end deftypefn
 
+@anchor{open_channel}
+@deftypefun int open_channel (emacs_env *@var{env}, emacs_value @var{pipe_process})
+This function, which is available since Emacs 27, opens a channel to
+an existing pipe process.  @var{pipe_process} must refer to an
+existing pipe process created by @code{make-pipe-process}.  @ref{Pipe
+Processes}.  If successful, the return value will be a new file
+descriptor that you can use to write to the pipe.  Unlike all other
+module functions, you can use the returned file descriptor from
+arbitrary threads, even if no module environment is active.  You can
+use the @code{write} function to write to the file descriptor.  Once
+done, close the file descriptor using @code{close}.  @ref{Low-Level
+I/O,,,libc}.
+@end deftypefun
+
 @node Module Nonlocal
 @subsection Nonlocal Exits in Modules
 @cindex nonlocal exits, in modules