# -*- fill-column: 100; eval: (auto-fill-mode t) -*-

* Content                                                                            :TOC:noexport:
- [[#pfuture][Pfuture]]
   - [[#what-it-is][What it is]]
   - [[#practical-examples][Practical examples]]
      - [[#with-a-future-object][With a Future object]]
      - [[#with-a-callback][With a Callback]]
   - [[#about-asyncel][About async.el]]

* Pfuture
** What it is

pfuture.el offers a set of simple functions wrapping Emacs' existing process creation capabilities.
It allows to conveniently deal with external processes in an asynchronous manner without having to
worry about stdout buffers and filter- & sentinel-functions.

The following examples practically demonstrate its capabilities. Detailed and formal documentation
can be found in each function's eldoc.

** Practical examples

Pfuture has 2 entry points.

 - ~pfuture-new~ creates a ~future~ object that can be stored, passed around to other functions and
   awaited to completion.
 - ~pfuture-callback~ allows starting an external process in a fire-and-forget fashion, alongside
   callbacks to execute when the process succeeds or fails, with full access to its output.

*** With a Future object

We can use pfuture to start an artficially long-running process (simulated with a sleep of 3
seconds) twice and wait until both futures complete. Despite sleeping twice only 3 seconds will have
passed since the processes run in parallel.

#+BEGIN_SRC emacs-lisp
  (let ((start   (float-time))
        (future1 (pfuture-new "sleep" "3"))
        (future2 (pfuture-new "sleep" "3"))
        (future3 (pfuture-new "echo" "All futures have finished after %s seconds.")))
    (pfuture-await future1 :timeout 4 :just-this-one nil)
    (pfuture-await future2 :timeout 4 :just-this-one nil)
    (pfuture-await future3 :timeout 4 :just-this-one nil)
    (message (pfuture-result future3) (round (- (float-time) start))))
#+END_SRC

Stdout and stderr in future objects are separate:

#+BEGIN_SRC emacs-lisp
  (let ((future (pfuture-new "ls" "nonexsitent_file")))
    (pfuture-await-to-finish future)
    (message "Future stdout: [%s]" (string-trim (pfuture-result future)))
    (message "Future stderr: [%s]" (string-trim (pfuture-stderr future))))
#+END_SRC

Calls to ~pfuture-await~ (and especially ~pfuture-await-to-finish~) are blocking, so it is important
to set an appropriate timeout (default is 1 second) or to be really sure that the process is going
to terminate.

*** With a Callback

Here we start another process and instead of keeping the future around and eventually awaiting it we
can simply define what steps to take once the process has completed, depending on whether it failed
or not.

(Note that ~pfuture-callback~ requires lexical scope)

#+BEGIN_SRC emacs-lisp
  (defun showcase-error-callback (process status output)
    (message "Pfuture Error!")
    (message "Process: %s" process)
    (message "Status: %s" status)
    (message "Output: %s" output))

  (let ((debug-callback (lambda (pfuture-process status _pfuture-buffer)
                          (message "Pfuture Debug: Process [%s] changed sttaus to [%s]" pfuture-process status))))
    (pfuture-callback ["ls" "-alh" "."]
      :directory "~/Documents/git/pfuture"
      :name "Pfuture Example"
      :on-success (message "Pfuture Finish:\n%s" (pfuture-callback-output))
      :on-error #'showcase-error-callback
      :on-status-change debug-callback))
#+END_SRC

** About async.el

You might be inclined to compare both packages since they both, at first glance, handle asynchronous
processes, but in truth they have very little in common outside of their general asynchronous
nature.

Async.el allows you to start and handle an asynchronous Emacs instance, running Elisp code. Pfuture
lets you start any external command like ~git~ or ~ls~ (as its mostly a wrapper around
~make-process~), and then read its output. So while the two packages may appear similar at first
there is really nothing to compare.
