Added `async-start-process'

[gnu-emacs-elpa] / README.md

diff --git a/README.md b/README.md
index fb3e19115837010fe2acb8a8283cd042993a7708..39b14b9b671ea8f62bebd1d0a5757d9104be851d 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,10 +1,14 @@
 # emacs-async
 
-async.el is an exceedingly simple module for doing asynchronous processing in
-Emacs, by spawning a child Emacs interpreter to execute a lambda function, and
-calling back when the job is done.
+async.el is a module for doing asynchronous processing in Emacs.  The
+interface is intended to be very easy to use:
 
-It uses a very simple syntax:
+## async-start
+
+    async-start START-FUNC FINISH-FUNC
+    
+Execute START-FUNC (often a lambda) in a subordinate Emacs process.  When
+done, the return value is passed to FINISH-FUNC.  Example:
 
     (async-start
        ;; What to do in the child process
@@ -16,9 +20,9 @@ It uses a very simple syntax:
        ;; What to do when it finishes
        (lambda (result)
          (message "Async process done, result should be 222: %s" result)))
-
-If you omit the callback function, `async-start` returns a process object that
-you can call `async-get` on when you're ready to wait for the result value:
+             
+If FINISH-FUNC is nil or missing, a future is returned that can be inspected
+using `async-get', blocking until the value is ready.  Example:
 
     (let ((proc (async-start
                    ;; What to do in the child process
@@ -33,7 +37,7 @@ you can call `async-get` on when you're ready to wait for the result value:
                  (async-get proc)))
 
 If you don't want to use a callback, and you don't care about any return value
-form the child process, pass the `ignore` symbol as the second argument (if
+form the child process, pass the `ignore' symbol as the second argument (if
 you don't, and never call `async-get', it will leave *emacs* process buffers
 hanging around):
 
@@ -41,3 +45,57 @@ hanging around):
      (lambda ()
        (delete-file "a remote file on a slow link" nil))
      'ignore)
+
+Note: Even when FINISH-FUNC is present, a future is still returned except that
+it yields no value (since the value is passed to FINISH-FUNC).  Call
+`async-get' on such a future always returns nil.  It can still be useful,
+however, as an argument to `async-ready' or `async-wait'.
+
+## async-start-process
+
+    async-start-process NAME PROGRAM FINISH-FUNC &rest PROGRAM-ARGS
+    
+Start the executable PROGRAM asynchronously.  See `async-start'.  PROGRAM is
+passed PROGRAM-ARGS, calling FINISH-FUNC with the process object when done.
+If FINISH-FUNC is nil, the future object will return the process object when
+the program is finished.
+
+## async-get
+
+    async-get FUTURE
+    
+Get the value from an asynchronously function when it is ready.  FUTURE is
+returned by `async-start' or `async-start-process' when its FINISH-FUNC is
+nil.
+
+## async-ready
+
+    async-ready FUTURE
+
+Query a FUTURE to see if the ready is ready -- i.e., if no blocking
+would result from a call to `async-get' on that FUTURE.
+
+## async-wait
+
+    async-wait FUTURE
+
+Wait for FUTURE to become ready.
+
+## async-inject-variables
+
+    async-inject-variables INCLUDE-REGEXP &optional PREDICATE EXCLUDE-REGEXP
+
+Return a `setq' form that replicates part of the calling environment.  It sets
+the value for every variable matching INCLUDE-REGEXP and also PREDICATE.  It
+will not perform injection for any variable matching EXCLUDE-REGEXP (if
+present).  It is intended to be used as follows:
+
+    (async-start
+       `(lambda ()
+          (require 'smtpmail)
+          (with-temp-buffer
+            (insert ,(buffer-substring-no-properties (point-min) (point-max)))
+            ;; Pass in the variable environment for smtpmail
+            ,(async-inject-variables "\\`\\(smtpmail\\|\\(user-\\)?mail\\)-")
+            (smtpmail-send-it)))
+       'ignore)