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