commit ba8444602949408646a07b7815685a3131c3aa95
Author: Max Rottenkolber <max@mr.gy>
Date:   Sun Jul 26 20:44:44 2015 +0200

    Add q-thread-pool documentation.

diff --git a/software/q-thread-pool/api.mk2 b/software/q-thread-pool/api.mk2
new file mode 100644
index 0000000..a5c6d3e
--- /dev/null
+++ b/software/q-thread-pool/api.mk2
@@ -0,0 +1,96 @@
+< q-thread-pool
+
+ Simple thread pools based on concurrent queues.
+
+
+ < Example Usage
+
+  Use {make-thread-pool} to create a thread pool with 16 threads and a
+  backlog of 32 and bind it to {pool}.
+
+  #code#
+(setq pool (make-thread-pool 16 32))
+  #
+
+  Use {enqueue-task} to enqueue 64 tasks for parallel evaluation by
+  {pool}. Note that the body forms of {enqueue-task} is a lexical
+  closure. The threads of {pool} will work off the backlog concurrently.
+  Once the backlog is full, e.g. when there are already 32 other tasks
+  waiting, {enqueue-task} will block until there is room in the queue.
+
+  #code#
+(let ((out *standard-output*))
+  (dotimes (i 64)
+    (enqueue-task pool
+      (sleep 5)
+      (write-string "x" out))))
+  #
+
+  When {pool} is no longer needed, its threads should be destroy using
+  {destroy-thread-pool} in order to avoid leaking resources.
+
+  #code#
+(destroy-thread-pool pool)
+  #
+
+ >
+
+
+ < destroy-thread-pool \(Function\)
+
+  *Syntax:*
+
+  — Function: *destroy-thread-pool* _thread-pool_
+
+  *Arguments and Values:*
+
+  _thread-pool_—a thread pool.
+
+  *Description*:
+
+  {destroy-thread-pool} destroys all threads allocated by _thread-pool_.
+
+ >
+
+
+ < enqueue-task \(Macro\)
+
+  *Syntax:*
+
+  — Macro: *enqueue-task* _thread-pool_ {&body} _forms_
+
+  *Arguments and Values:*
+
+  _thread-pool_—a thread pool.
+
+  _forms_—_forms_.
+
+  *Description*:
+
+  {enqueue-task} enqueues a _lexical closure_ containing _forms_ for
+  evaluation by _thread-pool_. If the backlog of of _thread-pool_ is full
+  {enqueue-task} will block until another task is dequeued.
+
+ >
+
+
+ < make-thread-pool \(Function\)
+
+  *Syntax:*
+
+  — Function: *make-thread-pool* _size_ _backlog_
+
+  *Arguments and Values:*
+
+  _size_, _backlog_—positive _integers_.
+
+  *Description*:
+
+  {make-thread-pool} returns a thread pool. _Size_ is the number of
+  threads in the pool. _Backlog_ is the number of tasks that will be
+  queued before {enqueue-task} blocks.
+
+ >
+
+>
+