Andreas Enge on Tue, 12 Jan 2016 16:22:28 +0100

 [PATCH] doc: Rewrite documentation for parfor.

A patch is attached for the documentation of parfor. Comments and corrections
are welcome before I push.

Andreas


>From a09187030fecca0174aea6c8f91bb4450aa6b592 Mon Sep 17 00:00:00 2001
From: Andreas Enge <andreas.enge@inria.fr>
Date: Tue, 12 Jan 2016 16:18:56 +0100
Subject: [PATCH] doc: Rewrite documentation for parfor.

* src/functions/programming/parfor (Help, Doc): Modify them.
---
src/functions/programming/parfor | 62 +++++++++++++++++++++++++++++++++-------
1 file changed, 51 insertions(+), 11 deletions(-)

diff --git a/src/functions/programming/parfor b/src/functions/programming/parfor
index 9fb25f2..71e994c 100644
--- a/src/functions/programming/parfor
+++ b/src/functions/programming/parfor
@@ -4,19 +4,59 @@ C-Name: parfor0
Prototype: vV=GDGJDVDI
Description:
(gen,gen,closure):void parfor($1,$2, $3, NULL, NULL) -Help: parfor(i=a,{b},expr1,{j},{expr2}): evaluates the sequence expr2 - (dependent on i and j) for i between a and b, in random order, computed - in parallel. Substitute for j the value of expr1 (dependent on i). - If b is omitted, the loop will not stop. -Doc: evaluates the sequence \kbd{expr2} (dependent on$i$and$j$) for$i$- between$a$and$b$, in random order, computed in parallel; in this sequence - \kbd{expr2}, substitute the variable$j$by the value of \kbd{expr1} - (dependent on$i$). If$b$is omitted, the loop will not stop. +Help: parfor(i=a,{b},expr1,{r},{expr2}): + evaluates the expression expr1 in parallel for all i between a and b + (if b is omitted, the loop will not stop), resulting in as many + values; if the formal variable r and expr2 are present, evaluate + sequentially expr2, in which r has been replaced by the different results + obtained for expr1. +Doc: evaluates in parallel the expression \kbd{expr1} in the formal + argument$i$running from$a$to$b$. + If$b$is omitted, the loop runs indefinitely. + If$r$and \kbd{expr2} are present, the expression \kbd{expr2} in the + formal variable$r$is evaluated with$r$running through all the different + results obtained for \kbd{expr1}. + + The computations of \kbd{expr1} are \emph{started} in increasing order + of$i$; otherwise said, the computation for$i=c$is started after those + for$i=1, \ldots, c-1$have been started, but before the computation for +$i=c+1$is started. Notice that the order of \emph{completion}, that is, + the order in which the different$r$become available, may be different; + \kbd{expr2} is evaluated sequentially on each$r$as it appears. + + The following example computes the sum of the squares of the integers + from$1$to$10$by computing the squares in parallel and is equivalent + to \kbd{parsum (i=1, 10, i\^{}2)}: + \bprog + ? s=0; + ? parfor (i=1, 10, i^2, r, s=s+r) + ? s + %3 = 385 + @eprog + More precisely, apart from a potentially different order of evaluation + due to the parallelism, the line containing \kbd{parfor} is equivalent to + \bprog + ? my (r); for (i=1, 10, r=i^2; s=s+r) + @eprog + The sequentiality of the evaluation of \kbd{expr2} ensures that the + variable \kbd{s} is not modified concurrently by two different additions, + although the order in which the terms are added is non-deterministic. It is allowed for \kbd{expr2} to exit the loop using - \kbd{break}/\kbd{next}/\kbd{return}; however in that case, \kbd{expr2} will - still be evaluated for all remaining value of$i$less than the current one, - unless a subsequent \kbd{break}/\kbd{next}/\kbd{return} happens. + \kbd{break}/\kbd{next}/\kbd{return}. If that happens for$i=c$, + then the evaluation of \kbd{expr1} and \kbd{expr2} is continued + for all values$i<c$, and the return value is the one obtained for + the smallest$i$causing an interruption in \kbd{expr2} (it may be + undefined if this is a \kbd{break}/\kbd{next}). + In that case, using side-effects + in \kbd{expr2} may lead to undefined behavior, as the exact + number of values of$i\$ for which it is executed is non-deterministic.
+ The following example computes \kbd{nextprime(1000)} in parallel:
+ \bprog
+ ? parfor (i=1000, , [i, isprime (i)], r, if (r [2], return (r [1])))
+ %1 = 1009
+ @eprog
+
%\syn{NO}

Function: _parfor_worker
--
2.6.3