From c3b17c74fb8a124b19ecc4b7efc611b57abc06f2 Mon Sep 17 00:00:00 2001 From: neunhoef Date: Fri, 23 Jul 2010 22:43:42 +0000 Subject: [PATCH] Finishing touches. git-svn-id: svn://helios.math.rwth-aachen.de/home2/thuban/svnuser/REPOSITORY/io/trunk@372 fe943924-0cfe-0310-992e-f7ec16831e91 --- HISTORY | 2 +- TODO | 7 +-- doc/main.xml | 145 ++++++++++++++++++++++++++++++++++++++++++++++----- 3 files changed, 138 insertions(+), 16 deletions(-) diff --git a/HISTORY b/HISTORY index e688ba0..8aced2a 100644 --- a/HISTORY +++ b/HISTORY @@ -1,7 +1,7 @@ Version history: Version SVN revision date -3.1 ? 21 July 2010 +3.1 372 23 July 2010 3.0 342 8 April 2009 2.3 328 3 October 2007 2.2 296 2 April 2007 diff --git a/TODO b/TODO index cff27c5..0f2d9bf 100644 --- a/TODO +++ b/TODO @@ -1,16 +1,17 @@ -Background jobs +Later: Compiling on Snow-Leopard -> email Alex K Sep 10 2009 -Later: +Sort out SIGCHLD handler issues, cooperate with GAP kernel's handler getcwd --> update GAPInfo.CurrentDirectory License issues? Go to GPL 3? -HTTP access scheint nicht mehr zu funktionieren --> debug +HTTP access scheint nicht immer zu funktionieren --> debug offenbar warte ich bei nicht ang. contentlength fuer immer (ev. nur bei "chunked access"???) + --> www.tagesschau.de z.B. HTTP/1.1-Konformitaet -> Alexander Konovalovs Tests mit Online int seq site chunked transfer diff --git a/doc/main.xml b/doc/main.xml index 2aef83e..c621174 100644 --- a/doc/main.xml +++ b/doc/main.xml @@ -2324,7 +2324,7 @@ over a pipe to the child process. A special case is if the argument args is equal to fail, in this case the child process is started but does not automatically call fun but rather waits in an idle state until an argument list is submitted via the -pipe using the operation described below. +pipe using the operation described below.

There are two components defined which can be bound in the options record opt. One is TerminateImmediately, if this is bound to true @@ -2332,9 +2332,9 @@ then the child process immediately terminates after the function fun returns its result. In this case, no pipe for communication from parent to child is created since it would never be used. Note that in this case one can still get the result of the function fun using the - operation described below, even when the child -has already terminated, since the result is first transmitted back to the -parent before termination. + operation described below, even when +the child has already terminated, since the result is first transmitted +back to the parent before termination. @@ -2342,7 +2342,7 @@ The following operations are available to deal with background job objects: - + true, false or fail This operation checks whether or not the background job represented by @@ -2352,7 +2352,8 @@ is still running and working on the worker function, false is returned. If the background job has already terminated altogether, this operation returns fail. Note that if a child process terminates automatically after the first completion of its worker function and sending the result, -then the first call to after completion will return +then the first call to +after completion will return true to indicate successful completion and all subsequent calls will return fail. @@ -2381,7 +2382,7 @@ the parent process. If the child process has died before completion - + the result of the worker function or fail This operation does the same as . @@ -2389,16 +2390,18 @@ This operation does the same as . - + true or fail This submits another argument list args for another call to the worker function in the background job job. It is an error if either the background job has already terminated or if it is still busy working on the previous argument list. That is, one must only submit -another argument in a situation when would return +another argument in a situation when +would return true. This is for example the case directly after a successful -call to or which did +call to or i + which did not return fail, unless the background job was created with the TerminateImmediately option set to true.

@@ -2410,14 +2413,14 @@ argument list. - + nothing This kills the background job represented by the object job with immediate effect. No more results can be expected from it. Note that unless one has created the background job with the TerminateImmediately option set to true one always -has to call on a background job eventually +has to call on a background job eventually for cleanup purposes. Otherwise, the background job and the connecting pipes remain alive until the parent ⪆ process terminates. @@ -2531,6 +2534,124 @@ dominates the communication time for a single result. +Note that the next parallel skeleton is a worker farm which +is described in the following section. + + +

+Worker farms + +The parallel skeleton of a worker farm is basically nothing but +a bunch of background jobs all with the same worker function and +all eagerly waiting for work. The only additional concepts needed +are an input and an output queue. The input queue contains +argument lists and the output queue pairs of argument lists +and results. + +

+One creates a worker farm with the following operation: + + +an object representing the worker farm or fail + +This operation creates a worker farm with the worker function +fun and sets up its input and output queue. An object representing +the farm is returned unless not all jobs could be started up in which +case fail is returned. After startup all background jobs in the +farm are idle. The only valid option in the options record opt +is NumberJobs and it must be bound to the number of worker +jobs in the farm, a positive integer. + + + +The following operations are for worker farm objects: + + + + nothing + +This operation called on a worker farm object wf administrates +the input and output queues of the worker farm. In particular it +checks whether new results are available from the workers and if so +it appends them to the output queue. If jobs are idle and the input +queue is non-empty, argument lists from the input queue are sent +to the idle jobs and removed from the input queue. +

+This operation must be called regularly to keep up the communication +with the clients. It uses select and so does not +block if the boolean argument block is set to false. +However, if larger chunks of data has to be sent or received this +operation might need some time to return. +

+If the boolean argument block is set to true then the + blocks until at least one job has returned +a result. This can be used to wait for the termination of all tasks +without burning CPU cycles in the parent job. One would repeatedly +call with block set to true +and after each such call check with +whether all tasks are done. Note that one should no longer call + with block set to true once +this is the case since then it would block forever. +

+This operation is called automatically by most of the following +operations. + + + + + + nothing + +This operation terminates all background jobs in the farm wf, +which cannot be used subsequently. One should always call this operation +when the worker farm is no longer needed to free resources. + + + + + + true or false + +This operation returns true if all background jobs in the +worker farm wf are idle. This means, that all tasks which +have previously been submitted using have +been completed and their result been appended to the output +queue. The operation is automatically +called before the execution of . + + + + + + nothing + +This operation submits a task in the form of an argument list for the +worker function to the worker farm. It is appended at the end of the +input queue. +The operation is automatically +called after the execution of , giving the +farm a chance to actually send the work out to the worker background +jobs. + + + + + + nothing + +This operation collects all results from the output queue of the +worker farm. The output queue is empty after this function returns. +The results are reported as a list of pairs, each pair has the +input argument list as first component and the output object +as second component. +

+The operation is automatically +called before the execution of , giving the +farm a chance to actually receive some more results from the worker background +jobs. + + +