branch: externals/el-job
commit c85b4ca947bf281804799ffe0e0464619713afeb
Author: Martin Edström <meedstro...@gmail.com>
Commit: Martin Edström <meedstro...@gmail.com>
Readme
---
README.org | 24 ++++++++++++++----------
1 file changed, 14 insertions(+), 10 deletions(-)
diff --git a/README.org b/README.org
index 0173ec3898..ad789b1c3a 100644
--- a/README.org
+++ b/README.org
@@ -21,28 +21,32 @@ I want to shorten the round-trip as much as possible,
*between the start of an a
For example, say you have some lisp that collects completion candidates, and
you want to run it asynchronously because the lisp you wrote isn't always fast
enough to avoid the user's notice, but you'd still like it to return as soon as
possible.
*** Processes stay alive
-A user might rarely delay longer than 100 ms between opening the minibuffer
and beginning to type, so there's scant room for overhead like spinning up
subprocesses that load a bunch of libraries before getting to work.
+In the above example, a user might not delay longer than 100 ms between
opening the minibuffer and beginning to type, so there's scant room for
overhead like spinning up subprocesses that load a bunch of libraries before
getting to work.
-Thus el-job makes them stick around for up to 30 seconds, awaiting more input.
+Thus el-job keeps idle subprocesses for up to 30 seconds after a job finishes,
awaiting more input.
-An aesthetic drawback is cluttering your task manager with many entries called
=emacs=. Users who tend to run system commands such as =pkill emacs= may find
that the command occasionally "does not work".
+An aesthetic drawback is cluttering your task manager with many processes
named "emacs".
+
+Users who tend to run system commands such as =pkill emacs= may find that the
command occasionally "does not work", because it actually killed an el-job
subprocess instead of the Emacs they see on screen.
*** Emacs 30 =fast-read-process-output=
-Some libraries, such as
[[https://github.com/jwiegley/emacs-async/][async.el]], internally rely on a
custom process filter. Since Emacs 30, it's a particularly good idea to use
the built-in process filter when performance is critical, and thus that's what
el-job does.
+Some other libraries, like the popular
[[https://github.com/jwiegley/emacs-async/][async.el]], internally rely on a
custom process filter. Since Emacs 30, it's a good idea to use the built-in
process filter when performance is critical, and thus that's what el-job does.
A corollary: if you're testing this on Emacs 29 or below, you don't see this
library at its best performance.
** News 1.0.0
- No longer keeps processes alive forever. All jobs are kept alive for up to
30 seconds of disuse, then reaped.
-- Pruned many code paths
+- Pruned many code paths.
- Many arguments changed, and a few were removed. Consult the docstring of
=el-job-launch= again.
- Users of Emacs 29 and below may see a worsened performance in el-job v1.0
compared to v0.3; this is temporary and will be rectified.
** Limitations
-1. I *may or may not drop support for Emacs 28 and 29* in mid-2025, one month
after the release after Debian trixie. For something backwards-compatible, try
[[https://github.com/jwiegley/emacs-async/][async.el]].
+1. *May or may not drop support for Emacs 28 and 29* in mid-2025, one month
after the [[https://release.debian.org/trixie/freeze_policy.html][release of
Debian trixie]]. For a project with longer back-compat, try
[[https://github.com/jwiegley/emacs-async/][async.el]].
+
+2. The return value from the =:funcall-per-input= function must always be a
list with a fixed length, where the elements are themselves lists.
-2. The return value from the =:funcall-per-input= function must always be a
list with a fixed length, where the elements are themselves lists. For
example, see the return value at the end of
[[https://github.com/meedstrom/org-node/blob/main/org-node-parser.el][org-node-parser.el]]:
+ For example, org-node passes =:funcall-per-input
#'org-node-parser--scan-file=, and this is the return value of
[[https://github.com/meedstrom/org-node/blob/main/org-node-parser.el][org-node-parser--scan-file]]:
#+begin_src elisp
(list (if missing-file (list missing-file)) ; List of 1 item or nil
@@ -53,10 +57,10 @@ A corollary: if you're testing this on Emacs 29 or below,
you don't see this lib
(if problem (list problem)))) ; List of 1 item or nil
#+end_src
- May seem clunky to return lists of only one item, but you could consider it
a minor expense in exchange for simpler library code.
+ It may seem clunky to return lists of only one item, but you could consider
it a minor expense in exchange for simpler library code.
3. Some data types cannot be exchanged with the children: those whose printed
form look like =#<...>=. For example, =#<buffer notes.org>=, =#<obarray
n=94311>=, =#<marker at 3102 in README.org>=.
- To my knowledge, this sort of data usually has meaning only within the
current process, so you would never want to do that anyway.
+ IIUC, this sort of data only has meaning within the current process -- so
even if you could send it, it would not be usable by the recipient anyway.
- In days past, hash tables also took that form, but not since Emacs 25 or
so: their printed form looks like =#s(hash-table data ...)=, which works fine
to send.
+ In days past, hash tables also looked like that when printed, but not since
Emacs 25 or so: they now look like =#s(hash-table data ...)=, which works fine
to read back.
