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