[elpa] externals/plz a6cb9bd0e2 4/7: Docs: Queueing

[ELPA Syncer]

branch: externals/plz
commit a6cb9bd0e2df667967e924937a6114ca9077e41d
Author: Adam Porter <adam@alphapapa.net>
Commit: Adam Porter <adam@alphapapa.net>

    Docs: Queueing
---
 README.org | 32 +++++++++++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/README.org b/README.org
index 2ef7ba2702..642d90dec7 100644
--- a/README.org
+++ b/README.org
@@ -19,6 +19,7 @@
 - [[#usage][Usage]]
   - [[#examples][Examples]]
   - [[#functions][Functions]]
+  - [[#queueing][Queueing]]
 - [[#changelog][Changelog]]
 - [[#credits][Credits]]
 - [[#development][Development]]
@@ -44,7 +45,7 @@ This library isn't on MELPA yet.
 :TOC:      :depth 1
 :END:
 
-The only public function is ~plz~, which sends an HTTP request and returns 
either the result of the specified type (for a synchronous request), or the 
~curl~ process object (for asynchronous requests).  For asynchronous requests, 
callback, error-handling, and finalizer functions may be specified, as well as 
various other options.
+The main public function is ~plz~, which sends an HTTP request and returns 
either the result of the specified type (for a synchronous request), or the 
~curl~ process object (for asynchronous requests).  For asynchronous requests, 
callback, error-handling, and finalizer functions may be specified, as well as 
various other options.
 
 ** Examples
 
@@ -132,6 +133,35 @@ Synchronously download a JPEG file, then create an Emacs 
image object from the d
 
    ~NOQUERY~ is passed to ~make-process~, which see.
 
+** Queueing
+
+~plz~ provides a simple system for queueing HTTP requests.  First, make a 
~plz-queue~ struct by calling ~make-plz-queue~.  Then call ~plz-queue~ with the 
struct as the first argument, and the rest of the arguments being the same as 
those passed to ~plz~.  Then call ~plz-run~ to run the queued requests.
+
+All of the queue-related functions return the queue as their value, making 
them easy to use.  For example:
+
+#+begin_src elisp
+  (defvar my-queue (make-plz-queue :limit 2))
+
+  (plz-run
+   (plz-queue my-queue
+     'get "https://httpbin.org/get?foo=0";
+     :then (lambda (body) (message "%s" body))))
+#+end_src
+
+Or:
+
+#+begin_src elisp
+  (let ((queue (make-plz-queue :limit 2))
+        (urls '("https://httpbin.org/get?foo=0";
+                "https://httpbin.org/get?foo=1";)))
+    (plz-run
+     (dolist (url urls queue)
+       (plz-queue queue 'get url
+         :then (lambda (body) (message "%s" body))))))
+#+end_src
+
+You may also clear a queue with ~plz-clear~, which cancels any active or 
queued requests and calls their ~:else~ functions.  And ~plz-length~ returns 
the number of a queue's active and queued requests.
+
 ** Tips
 :PROPERTIES:
 :TOC:      :ignore (this)