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     (autoload 'dired-async-mode "dired-async.el" nil t)
  10     (dired-async-mode 1)
  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 disable it with `dired-async-mode`.
  20
  21 # Usage
  22
  23 The interface is intended to be very easy to use:
  24
  25 ## async-start
  26
  27     async-start START-FUNC FINISH-FUNC
  28
  29 Execute START-FUNC (often a lambda) in a subordinate Emacs process.  When
  30 done, the return value is passed to FINISH-FUNC.  Example:
  31
  32     (async-start
  33        ;; What to do in the child process
  34        (lambda ()
  35          (message "This is a test")
  36          (sleep-for 3)
  37          222)
  38
  39        ;; What to do when it finishes
  40        (lambda (result)
  41          (message "Async process done, result should be 222: %s" result)))
  42
  43 If FINISH-FUNC is `nil` or missing, a future is returned that can be inspected
  44 using `async-get`, blocking until the value is ready.  Example:
  45
  46     (let ((proc (async-start
  47                    ;; What to do in the child process
  48                    (lambda ()
  49                      (message "This is a test")
  50                      (sleep-for 3)
  51                      222))))
  52
  53         (message "I'm going to do some work here") ;; ....
  54
  55         (message "Waiting on async process, result should be 222: %s"
  56                  (async-get proc)))
  57
  58 If you don't want to use a callback, and you don't care about any return value
  59 from the child process, pass the `'ignore` symbol as the second argument (if
  60 you don't, and never call `async-get`, it will leave ``*emacs*`` process buffers
  61 hanging around):
  62
  63     (async-start
  64      (lambda ()
  65        (delete-file "a remote file on a slow link" nil))
  66      'ignore)
  67
  68 Note: Even when FINISH-FUNC is present, a future is still returned except that
  69 it yields no value (since the value is passed to FINISH-FUNC).  Calling
  70 `async-get` on such a future always returns `nil`.  It can still be useful,
  71 however, as an argument to `async-ready` or `async-wait`.
  72
  73 ## async-start-process
  74
  75     async-start-process NAME PROGRAM FINISH-FUNC &rest PROGRAM-ARGS
  76
  77 Start the executable PROGRAM asynchronously.  See `async-start`.  PROGRAM is
  78 passed PROGRAM-ARGS, calling FINISH-FUNC with the process object when done.
  79 If FINISH-FUNC is `nil`, the future object will return the process object when
  80 the program is finished.  Set DEFAULT-DIRECTORY to change PROGRAM's current
  81 working directory.
  82
  83 ## async-get
  84
  85     async-get FUTURE
  86
  87 Get the value from an asynchronously called 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 its function's value 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)