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

   1 <p><a href="http://www.gnu.org/licenses/gpl-3.0.txt"><img src="https://img.shields.io/badge/license-GPL_3-green.svg" alt="License GPL 3" /></a>
   2 <a href="http://melpa.org/#/async"><img src="http://melpa.org/packages/async-badge.svg" alt="MELPA" title="" /></a>
   3 <a href="http://stable.melpa.org/#/async"><img src="http://stable.melpa.org/packages/async-badge.svg" alt="MELPA Stable" title="" /></a></p>
   4
   5
   6 # emacs-async
   7
   8 `async.el` is a module for doing asynchronous processing in Emacs.
   9
  10 # Install
  11
  12 ## Install dired-async
  13
  14 Add to your `.emacs.el`:
  15
  16     (autoload 'dired-async-mode "dired-async.el" nil t)
  17     (dired-async-mode 1)
  18
  19 This will allow you to run  asynchronously
  20 the dired commands for copying, renaming and symlinking.
  21 If you are a [helm](https://github.com/emacs-helm/helm) user, this will allow you
  22 to copy, rename etc... asynchronously from [helm](https://github.com/emacs-helm/helm).
  23 Note that with [helm](https://github.com/emacs-helm/helm)
  24 you can disable this by running the copy, rename etc... commands with a prefix argument.
  25
  26 If you don't want to make dired/helm asynchronous disable it with `dired-async-mode`.
  27
  28 ### Debian and Ubuntu
  29
  30 Users of Debian 9 or later or Ubuntu 16.04 or later may simply `apt-get install elpa-async`.
  31
  32 ## Enable asynchronous compilation of your (M)elpa packages
  33
  34 By default emacs package.el compile packages in its running emacs session.
  35 This is not a problem when installing a new package (which is not actually loaded in current emacs)
  36 but it may create errors and bad compilation when upgrading a package (old version of package is already loaded
  37 and running in current emacs).
  38 You can remedy to this by allowing async to compile your packages asynchronously,
  39 (helm and magit actually do this by default,
  40 so if you are using these packages they will compile asynchronously)
  41 to do this, add to your init file:
  42
  43     (async-bytecomp-package-mode 1)
  44
  45
  46 You can control which packages will compile async with `async-bytecomp-allowed-packages`.
  47 Set it to `'(all)` to be sure you will compile all packages asynchronously.
  48
  49 # Usage
  50
  51 The interface is intended to be very easy to use:
  52
  53 ## async-start
  54
  55     async-start START-FUNC FINISH-FUNC
  56
  57 Execute START-FUNC (often a lambda) in a subordinate Emacs process.  When
  58 done, the return value is passed to FINISH-FUNC.  Example:
  59
  60     (async-start
  61        ;; What to do in the child process
  62        (lambda ()
  63          (message "This is a test")
  64          (sleep-for 3)
  65          222)
  66
  67        ;; What to do when it finishes
  68        (lambda (result)
  69          (message "Async process done, result should be 222: %s" result)))
  70
  71 If FINISH-FUNC is `nil` or missing, a future is returned that can be inspected
  72 using `async-get`, blocking until the value is ready.  Example:
  73
  74     (let ((proc (async-start
  75                    ;; What to do in the child process
  76                    (lambda ()
  77                      (message "This is a test")
  78                      (sleep-for 3)
  79                      222))))
  80
  81         (message "I'm going to do some work here") ;; ....
  82
  83         (message "Waiting on async process, result should be 222: %s"
  84                  (async-get proc)))
  85
  86 If you don't want to use a callback, and you don't care about any return value
  87 from the child process, pass the `'ignore` symbol as the second argument (if
  88 you don't, and never call `async-get`, it will leave ``*emacs*`` process buffers
  89 hanging around):
  90
  91     (async-start
  92      (lambda ()
  93        (delete-file "a remote file on a slow link" nil))
  94      'ignore)
  95
  96 Note: Even when FINISH-FUNC is present, a future is still returned except that
  97 it yields no value (since the value is passed to FINISH-FUNC).  Calling
  98 `async-get` on such a future always returns `nil`.  It can still be useful,
  99 however, as an argument to `async-ready` or `async-wait`.
 100
 101 ## async-start-process
 102
 103     async-start-process NAME PROGRAM FINISH-FUNC &rest PROGRAM-ARGS
 104
 105 Start the executable PROGRAM asynchronously.  See `async-start`.  PROGRAM is
 106 passed PROGRAM-ARGS, calling FINISH-FUNC with the process object when done.
 107 If FINISH-FUNC is `nil`, the future object will return the process object when
 108 the program is finished.  Set DEFAULT-DIRECTORY to change PROGRAM's current
 109 working directory.
 110
 111 ## async-get
 112
 113     async-get FUTURE
 114
 115 Get the value from an asynchronously called function when it is ready.  FUTURE is
 116 returned by `async-start` or `async-start-process` when its FINISH-FUNC is
 117 `nil`.
 118
 119 ## async-ready
 120
 121     async-ready FUTURE
 122
 123 Query a FUTURE to see if its function's value is ready -- i.e., if no blocking
 124 would result from a call to `async-get` on that FUTURE.
 125
 126 ## async-wait
 127
 128     async-wait FUTURE
 129
 130 Wait for FUTURE to become ready.
 131
 132 ## async-inject-variables
 133
 134     async-inject-variables INCLUDE-REGEXP &optional PREDICATE EXCLUDE-REGEXP
 135
 136 Return a `setq` form that replicates part of the calling environment.  It sets
 137 the value for every variable matching INCLUDE-REGEXP and also PREDICATE.  It
 138 will not perform injection for any variable matching EXCLUDE-REGEXP (if
 139 present).  It is intended to be used as follows:
 140
 141     (async-start
 142        `(lambda ()
 143           (require 'smtpmail)
 144           (with-temp-buffer
 145             (insert ,(buffer-substring-no-properties (point-min) (point-max)))
 146             ;; Pass in the variable environment for smtpmail
 147             ,(async-inject-variables "\\`\\(smtpmail\\|\\(user-\\)?mail\\)-")
 148             (smtpmail-send-it)))
 149        'ignore)