doco new parallel funcs from news file

[Kevin Ryde]

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.

NEWS.parallel.diff
Description: Text document