Document some things

knots/parallelism.scm

@@ -96,6 +96,9 @@
      responses)))
 
 (define (fibers-batch-map proc parallelism-limit . lists)
+  "Map PROC over LISTS in parallel, with a PARALLELISM-LIMIT.  If any of
+the invocations of PROC raise an exception, this will be raised once
+all of the calls to PROC have finished."
   (define vecs (map (lambda (list-or-vec)
                       (if (vector? list-or-vec)
                           list-or-vec
@@ -171,9 +174,14 @@
                           channel-indexes)))))))
 
 (define (fibers-map proc . lists)
+  "Map PROC over LISTS in parallel, running up to 20 fibers in
+ PARALLEL.  If any of the invocations of PROC raise an exception, this
+will be raised once all of the calls to PROC have finished."
   (apply fibers-batch-map proc 20 lists))
 
 (define (fibers-batch-for-each proc parallelism-limit . lists)
+  "Call PROC on LISTS, running up to PARALLELISM-LIMIT fibers in
+parallel."
   (apply fibers-batch-map
          (lambda args
            (apply proc args)
@@ -184,10 +192,13 @@
   *unspecified*)
 
 (define (fibers-for-each proc . lists)
+  "Call PROC on LISTS, running up to 20 fibers in parallel."
   (apply fibers-batch-for-each proc 20 lists))
 
 (define-syntax fibers-parallel
   (lambda (x)
+    "Run each expression in parallel.  If any expression raises an
+ exception, this will be raised after all exceptions have finished."
     (syntax-case x ()
       ((_ e0 ...)
        (with-syntax (((tmp0 ...) (generate-temporaries (syntax (e0 ...)))))
@@ -198,12 +209,16 @@
              (apply values (fetch-result-of-defered-thunks tmp0 ...))))))))
 
 (define-syntax-rule (fibers-let ((v e) ...) b0 b1 ...)
+  "Let, but run each binding in a fiber in parallel."
   (call-with-values
       (lambda () (fibers-parallel e ...))
     (lambda (v ...)
       b0 b1 ...)))
 
 (define* (fibers-map-with-progress proc lists #:key report)
+  "Map PROC over LISTS, calling #:REPORT if specified after each
+invocation of PROC finishes.  REPORT is passed the results for each
+ element of LISTS, or #f if no result has been received yet."
   (let loop ((channels-to-results
               (apply map
                      (lambda args