code.delx.au - gnu-emacs-elpa/blob - README.md

   1 # emacs-async
   2
   3 async.el is a module for doing asynchronous processing in Emacs.  The
   4 interface is intended to be very easy to use:
   5
   6 ## async-start
   7
   8     async-start START-FUNC FINISH-FUNC
   9
  10 Execute START-FUNC (often a lambda) in a subordinate Emacs process.  When
  11 done, the return value is passed to FINISH-FUNC.  Example:
  12
  13     (async-start
  14        ;; What to do in the child process
  15        (lambda ()
  16          (message "This is a test")
  17          (sleep-for 3)
  18          222)
  19
  20        ;; What to do when it finishes
  21        (lambda (result)
  22          (message "Async process done, result should be 222: %s" result)))
  23
  24 If FINISH-FUNC is nil or missing, a future is returned that can be inspected
  25 using `async-get', blocking until the value is ready.  Example:
  26
  27     (let ((proc (async-start
  28                    ;; What to do in the child process
  29                    (lambda ()
  30                      (message "This is a test")
  31                      (sleep-for 3)
  32                      222))))
  33
  34         (message "I'm going to do some work here") ;; ....
  35
  36         (message "Waiting on async process, result should be 222: %s"
  37                  (async-get proc)))
  38
  39 If you don't want to use a callback, and you don't care about any return value
  40 form the child process, pass the `ignore' symbol as the second argument (if
  41 you don't, and never call `async-get', it will leave *emacs* process buffers
  42 hanging around):
  43
  44     (async-start
  45      (lambda ()
  46        (delete-file "a remote file on a slow link" nil))
  47      'ignore)
  48
  49 Note: Even when FINISH-FUNC is present, a future is still returned except that
  50 it yields no value (since the value is passed to FINISH-FUNC).  Call
  51 `async-get' on such a future always returns nil.  It can still be useful,
  52 however, as an argument to `async-ready' or `async-wait'.
  53
  54 ## async-start-process
  55
  56     async-start-process NAME PROGRAM FINISH-FUNC &rest PROGRAM-ARGS
  57
  58 Start the executable PROGRAM asynchronously.  See `async-start'.  PROGRAM is
  59 passed PROGRAM-ARGS, calling FINISH-FUNC with the process object when done.
  60 If FINISH-FUNC is nil, the future object will return the process object when
  61 the program is finished.
  62
  63 ## async-get
  64
  65     async-get FUTURE
  66
  67 Get the value from an asynchronously function when it is ready.  FUTURE is
  68 returned by `async-start' or `async-start-process' when its FINISH-FUNC is
  69 nil.
  70
  71 ## async-ready
  72
  73     async-ready FUTURE
  74
  75 Query a FUTURE to see if the ready is ready -- i.e., if no blocking
  76 would result from a call to `async-get' on that FUTURE.
  77
  78 ## async-wait
  79
  80     async-wait FUTURE
  81
  82 Wait for FUTURE to become ready.
  83
  84 ## async-inject-variables
  85
  86     async-inject-variables INCLUDE-REGEXP &optional PREDICATE EXCLUDE-REGEXP
  87
  88 Return a `setq' form that replicates part of the calling environment.  It sets
  89 the value for every variable matching INCLUDE-REGEXP and also PREDICATE.  It
  90 will not perform injection for any variable matching EXCLUDE-REGEXP (if
  91 present).  It is intended to be used as follows:
  92
  93     (async-start
  94        `(lambda ()
  95           (require 'smtpmail)
  96           (with-temp-buffer
  97             (insert ,(buffer-substring-no-properties (point-min) (point-max)))
  98             ;; Pass in the variable environment for smtpmail
  99             ,(async-inject-variables "\\`\\(smtpmail\\|\\(user-\\)?mail\\)-")
 100             (smtpmail-send-it)))
 101        'ignore)