Andreas Enge on Tue, 12 Jan 2016 16:22:28 +0100 |
[Date Prev] [Date Next] [Thread Prev] [Thread Next] [Date Index] [Thread Index]
[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