doco new parallel funcs from news file

[Kevin Ryde <user42@zip.com.au>]

[-- Attachment #1: Type: text/plain, Size: 3683 bytes --]

A bit more out of the news file and into the manual,

        * scheme-scheduling.texi (Higher level thread procedures): Add
        parallel, letpar, par-map, par-for-each, n-par-map, n-par-for-each,
        n-for-each-par-map.

I haven't actually been using these, so I've only copied what the news
file said and what I could guess.  Needs to be checked for accuracy.


 - syntax: parallel form1 ... formN
     Evaluate each given FORM, in parallel, each in a new thread.
     Return the results as a set of N multiple values (*note Multiple
     Values::).

 - syntax: letpar ((var expr) ...) body...
     Evaluate each EXPR, in parallel, each in a new thread, then bind
     the results to the corresponding VAR variables and evaluate BODY.

     This is like `let' (*note Local Bindings::), but the expressions
     in the bindings are evaluated in parallel.

 - Scheme Procedure: par-map proc lst1 ... lstN
 - Scheme Procedure: par-for-each proc lst1 ... lstN
     Call PROC on the elements of the given lists.  `par-map' returns a
     list comprising the return values from PROC.  `par-for-each'
     returns an unspecified value.

     The PROC calls are `(PROC ELEM1 ...  ELEMN)', where each ELEM is
     from the corresponding LST.  Each LST must be the same length.
     The calls are made in parallel, each in a new thread.  All calls
     are completed before the functions return.

     These functions are like `map' and `for-each' (*note List
     Mapping::), but make their PROC calls in parallel.

 - Scheme Procedure: n-par-map n proc lst1 ... lstN
 - Scheme Procedure: n-par-for-each n proc lst1 ... lstN
     Call PROC on the elements of the given lists, in the same way as
     `par-map' and `par-for-each' above, but use no more than N threads
     at any one time.  The order in which calls are initiated within
     that limit is unspecified.

     These functions are good for controlling resource consumption if
     each call might be costly, or if there are many to be made.  On a
     dual-CPU system for instance N=4 might be enough to keep the CPUs
     utilized, and not consume too much memory.

 - Scheme Procedure: n-for-each-par-map n sproc pproc lst1 ... lstN
     Apply PPROC to the elements of the given lists, and apply SPROC to
     each result returned by PPROC.  The final return value is
     unspecified.

     The calls are `(SPROC (PPROC ELEM1 ...  ELEMN))', where each ELEM
     is from the corresponding LST.  Each LST must have the same number
     of elements.

     The PPROC calls are made in parallel, in new threads.  The SPROC
     calls are made serially, in list element order, and only one at a
     time.  PPROC calls may execute in parallel with the SPROC calls.
     Exactly which thread makes each SPROC call is unspecified.

     No more than N threads are used at any one time.  The order in
     which PPROC calls are initiated within that limit is unspecified.
     All calls are completed before `n-for-each-par-map' returns.

     This function is designed for individual calculations that can be
     done in parallel, but with results needing to be handled serially,
     for instance to write them to a file.  The N limit on parallelism
     controls system resource usage when there are many calculations or
     when they might be costly.

     It will be seen that `n-for-each-par-map' is like a combination of
     `n-par-map' and `for-each',

          (for-each sproc (n-par-map pproc lst1 ... lstN))

     But the actual implementation is more efficient since each SPROC
     call, in turn, can be initiated once the relevant PPROC call has
     completed, it doesn't need to wait for all to finish.



[-- Attachment #2: NEWS.parallel.diff --]
[-- Type: text/plain, Size: 1789 bytes --]

--- NEWS.~1.396.~	2003-06-05 02:42:45.000000000 +1000
+++ NEWS	2003-06-07 18:01:49.000000000 +1000
@@ -283,37 +283,11 @@
 Futures are like promises, but begun immediately in a new thread.  See
 the "Futures" section in the reference manual.
 
-** New syntax: parallel FORM ...
+** New threading functions: parallel, letpar, par-map, and friends
 
-Compute the results of FORM ... in parallel (in a separate thread for
-each form) and return them as multiple values.
-
-** New syntax: letpar ((VAR EXP) ...) BODYFORM ...
-
-Like 'let' but evaluates the binding expressions EXP ... in parallel.
-
-** New functions: par-map, par-for-each PROC ARGLIST ...
-
-Like 'map' and 'for-each' but evaluate the procedure PROC in a
-separate thread for each (set of) argument(s).  All applications are
-guaranteed to be completed before the procedure returns.
-
-** New functions: n-par-map, n-par-for-each N PROC ARGLIST ...
-
-Like 'par-map' and 'par-for-each' but evaluate the procedure PROC in N
-threads.  This is useful when PROC uses large amounts of resources
-and/or the argument list(s) is/are long so that one thread per (set
-of) argument(s) would consume too much system resources.  On a
-dual-CPU system, N = 4 would often be a good choice.
-
-** New function: n-for-each-par-map N S-PROC P-PROC ARGLIST ...
-
-Using N parallel processes, apply S-PROC in serial order to each
-result of applying P-PROC to each set of arguments in the argument
-lists ARGLIST ...
-
-Like a composition of 'for-each' and 'n-par-map', but allows S-PROC to
-start processing while the results of P-PROC are being produced.
+These are convenient ways to run calculations in parallel in new
+threads.  See "High level thread procedures" in the manual for
+details.
 
 ** Fair mutexes and condition variables
 

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel