<p>Tasks provide mid- to high-level functionality for programmers to describe asynchronous workflows. A task is an asynchronously or synchronously executing job; functions exist to create tasks that are executed concurrently, on demand, or in the current thread; to wait for their completion, check their status, and retrieve any results.</p>
<p>Here is a simple example of sorting a list in the background:</p>
<p><code class="func">RunTask</code> (<a href="chap1_mj.html#X7DEC1649841E3813"><span class="RefLink">1.2-1</span></a>) dispatches a task to run in the background; a task is described by a function and zero or more arguments that are passed to <code class="func">RunTask</code> (<a href="chap1_mj.html#X7DEC1649841E3813"><span class="RefLink">1.2-1</span></a>). <code class="func">WaitTask</code> (<a href="chap1_mj.html#X861BC1488345C424"><span class="RefLink">1.2-9</span></a>) waits for the task to complete; and <code class="code">TaskResult</code> returns the result of the task.</p>
<p><code class="func">TaskResult</code> (<a href="chap1_mj.html#X7A86C732823E04B6"><span class="RefLink">1.2-11</span></a>) does an implicit <code class="func">WaitTask</code> (<a href="chap1_mj.html#X861BC1488345C424"><span class="RefLink">1.2-9</span></a>), so the second line above can actually be omitted:</p>
<p>You can use <code class="func">DelayTask</code> (<a href="chap1_mj.html#X85BC2BBC7EF5B22E"><span class="RefLink">1.2-3</span></a>) to delay executing the task until its result is actually needed.</p>
<p>Note that <code class="func">WaitTask</code> (<a href="chap1_mj.html#X861BC1488345C424"><span class="RefLink">1.2-9</span></a>) is used here to start execution of both tasks; otherwise, <code class="code">task2</code> would not be started until <code class="code">TaskResult(task1)</code> has been evaluated.</p>
<p>To start execution of a delayed task, you can also use <code class="code">ExecuteTask</code>. This has no effect if a task has already been running.</p>
<p>For convenience, you can also use <code class="func">ImmediateTask</code> (<a href="chap1_mj.html#X84AFD0FA7A4E3633"><span class="RefLink">1.2-7</span></a>) to execute a task synchronously (i.e., the task is started immediately and the call does not return until the task has completed).</p>
<p>This is indistinguishable from calling the function directly, but provides the same interface as normal tasks.</p>
<p>If e.g. you want to call a function only for its side-effects, it can be useful to ignore the result of a task. <code class="func">RunAsyncTask</code> (<a href="chap1_mj.html#X856288C27C62B14A"><span class="RefLink">1.2-4</span></a>) provides the necessary functionality. Such a task cannot be waited for and its result (if any) is ignored.</p>
<p>For more information on the multi-threaded user interface, see Chapter <a href="chap4_mj.html#X7AFF436381C319CD"><span class="RefLink">4</span></a>.</p>
<p>Task arguments are generally copied so that both the task that created them and the task that uses them can access the data concurrently without fear of race conditions. To avoid copying, arguments should be made shared or public (see the relevant parts of section <a href="chap3_mj.html#X87315FA584A37637"><span class="RefLink">3.6</span></a> on migrating objects between regions); shared and public arguments will not be copied.</p>
<p>HPC-GAP currently has multiple implementations of the task API. To use an alternative implementation to the one documented here, set the environment variable <code class="code">GAP_WORKSTEALING</code> to a non-empty value before starting GAP.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ RunTask</code>( <var class="Arg">func</var>[, <var class="Arg">arg1</var>, <var class="Arg">...</var>, <var class="Arg">argn</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">RunTask</code> prepares a task for execution and starts it. The task will call the function <var class="Arg">func</var> with arguments <var class="Arg">arg1</var> through <var class="Arg">argn</var> (if provided). The return value of <var class="Arg">func</var> is the result of the task. The <code class="func">RunTask</code> call itself returns a task object that can be used by functions that expect a task argument.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ScheduleTask</code>( <var class="Arg">condition</var>, <var class="Arg">func</var>[, <var class="Arg">arg1</var>, <var class="Arg">...</var>, <var class="Arg">argn</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">ScheduleTask</code> prepares a task for execution, but, unlike <code class="func">RunTask</code> (<a href="chap1_mj.html#X7DEC1649841E3813"><span class="RefLink">1.2-1</span></a>) does not start it until <var class="Arg">condition</var> is met. See on how to construct conditions. Simple examples of conditions are individual tasks, where execution occurs after the task completes, or lists of tasks, where execution occurs after all tasks in the list complete.</p>
<p>While the above example could also be achieved with <code class="func">RunTask</code> (<a href="chap1_mj.html#X7DEC1649841E3813"><span class="RefLink">1.2-1</span></a>) in lieu of <code class="func">ScheduleTask</code>, since <code class="func">TaskResult</code> (<a href="chap1_mj.html#X7A86C732823E04B6"><span class="RefLink">1.2-11</span></a>) would wait for <var class="Arg">t1</var> and <var class="Arg">t2</var> to complete, the above implementation does not actually start the final task until the others are complete, making it more efficient, since no additional worker thread needs to be occupied.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ DelayTask</code>( <var class="Arg">func</var>[, <var class="Arg">arg1</var>, <var class="Arg">...</var>, <var class="Arg">argn</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">DelayTask</code> works as <code class="func">RunTask</code> (<a href="chap1_mj.html#X7DEC1649841E3813"><span class="RefLink">1.2-1</span></a>), but its start is delayed until it is being waited for (including implicitly by calling <code class="func">TaskResult</code> (<a href="chap1_mj.html#X7A86C732823E04B6"><span class="RefLink">1.2-11</span></a>)).</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ RunAsyncTask</code>( <var class="Arg">func</var>[, <var class="Arg">arg1</var>, <var class="Arg">...</var>, <var class="Arg">argn</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">RunAsyncTask</code> creates an asynchronous task. It works like <code class="func">RunTask</code> (<a href="chap1_mj.html#X7DEC1649841E3813"><span class="RefLink">1.2-1</span></a>), except that its result will be ignored.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ScheduleAsyncTask</code>( <var class="Arg">condition</var>, <var class="Arg">func</var>[, <var class="Arg">arg1</var>, <var class="Arg">...</var>, <var class="Arg">argn</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">ScheduleAsyncTask</code> creates an asynchronous task. It works like <codeclass="func">ScheduleTask</code> (<a href="chap1_mj.html#X7A86AE967D2A9E94"><span class="RefLink">1.2-2</span></a>), except that its result will be ignored.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ MakeTaskAsync</code>( <var class="Arg">task</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">MakeTaskAsync</code> turns a synchronous task into an asynchronous task that cannot be waited for and whose result will be ignored.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ImmediateTask</code>( <var class="Arg">func</var>[, <var class="Arg">arg1</var>, <var class="Arg">...</var>, <var class="Arg">argn</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">ImmediateTask</code> executes the task specified by its arguments synchronously, usually within the current thread.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ExecuteTask</code>( <var class="Arg">task</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">ExecuteTask</code> starts <var class="Arg">task</var> if it is not already running. It has only an effect if its argument is a task returned by <code class="func">DelayTask</code> (<a href="chap1_mj.html#X85BC2BBC7EF5B22E"><span class="RefLink">1.2-3</span></a>); otherwise, it is a no-op.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ WaitTask</code>( <var class="Arg">task1</var>, <var class="Arg">...</var>, <var class="Arg">taskn</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ WaitTask</code>( <var class="Arg">condition</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ WaitTasks</code>( <var class="Arg">task1</var>, <var class="Arg">...</var>, <var class="Arg">taskn</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">WaitTask</code> waits until <var class="Arg">task1</var> through <var class="Arg">taskn</var> have completed; after that, it returns. Alternatively, a condition can be passed to <code class="func">WaitTask</code> in order to wait until a condition is met. See on how to construct conditions. <code class="func">WaitTasks</code> is an alias for <code class="func">WaitTask</code>.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ WaitAnyTask</code>( <var class="Arg">task1</var>, <var class="Arg">...</var>, <var class="Arg">taskn</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>The <code class="func">WaitAnyTask</code> function waits for any of its arguments to finish, then returns the number of that task.</p>
<p>One can pass a list of tasks to <code class="code">WaitAnyTask</code> as an argument; <code class="code">WaitAnyTask([task1, ..., taskn])</code> behaves identically to <code class="code">WaitAnyTask(task1, ..., taskn)</code>.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ TaskResult</code>( <var class="Arg">task</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>The <code class="func">TaskResult</code> function returns the result of a task. It implicitly calls <code class="func">WaitTask</code> (<a href="chap1_mj.html#X861BC1488345C424"><span class="RefLink">1.2-9</span></a>) if that is necessary. Multiple invocations of <code class="func">TaskResult</code> with the same task argument will not do repeated waits and always return the same value.</p>
<p>If the function executed by <var class="Arg">task</var> encounters an error, <code class="func">TaskResult</code> returns <code class="keyw">fail</code>. Whether <var class="Arg">task</var> encountered an error can be checked via <code class="func">TaskSuccess</code> (<a href="chap1_mj.html#X87BB5EF38415B923"><span class="RefLink">1.3-1</span></a>). In case of an error, the error message can be retrieved via <code class="func">TaskError</code> (<a href="chap1_mj.html#X85F42F5E7E04F3C2"><span class="RefLink">1.3-2</span></a>).</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ TaskSuccess</code>( <var class="Arg">task</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">TaskSuccess</code> waits for <var class="Arg">task</var> and returns <code class="keyw">true</code> if the it finished without encountering an error. Otherwise the function returns <code class="keyw">false</code>.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ TaskError</code>( <var class="Arg">task</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">TaskError</code> waits for <var class="Arg">task</var> and returns its error message, if it encountered an error. If it did not encounter an error, the function returns <code class="keyw">fail</code>.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ RunningTasks</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function returns the number of currently running tasks. Note that it is only an approximation and can change as new tasks are being started by other threads.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ TaskStarted</code>( <var class="Arg">task</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function returns true if the task has started executing (i.e., for any non-delayed task), false otherwise.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ TaskFinished</code>( <var class="Arg">task</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function returns true if the task has finished executing and its result is available, false otherwise.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ TaskIsAsync</code>( <var class="Arg">task</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function returns true if the task is asynchronous, true otherwise.</p>
<p>HPC-GAP uses a cooperative model for task cancellation. A programmer can request the cancellation of another task, but it is up to that other task to actually terminate itself. The tasks library has functions to request cancellation, to test for the cancellation state of a task, and to perform actions in response to cancellation requests.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ CancelTask</code>( <var class="Arg">task</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">CancelTask</code> submits a request that <var class="Arg">task</var> is to be cancelled.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ OnTaskCancellation</code>( <var class="Arg">exit_func</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">OnTaskCancellation</code> tests if cancellation for the current task has been requested. If so, then <var class="Arg">exit_func</var> will be called (as a parameterless function) and the current task will be aborted. The result of the current task will be the value of <varclass="Arg">exit_func()</var>.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ OnTaskCancellationReturn</code>( <var class="Arg">value</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">OnTaskCancellationReturn</code> is a convenience function that does the same as: <code class="code">OnTaskCancellation(function() return value; end);</code></p>
<p><code class="func">ScheduleTask</code> (<a href="chap1_mj.html#X7A86AE967D2A9E94"><span class="RefLink">1.2-2</span></a>) and <code class="func">WaitTask</code> (<a href="chap1_mj.html#X861BC1488345C424"><span class="RefLink">1.2-9</span></a>) can be made to wait on more complex conditions than just tasks. A condition is either a milestone, a task, or a list of milestones and tasks. <code class="func">ScheduleTask</code> (<a href="chap1_mj.html#X7A86AE967D2A9E94"><span class="RefLink">1.2-2</span></a>) starts its task and <code class="func">WaitTask</code> (<a href="chap1_mj.html#X861BC1488345C424"><span class="RefLink">1.2-9</span></a>) returns when the condition has been met. A condition represented by a task is met when the task has completed. A condition represented by a milestone is met when the milestone has been achieved (see below). A condition represented by a list is met when all conditions in the list have been met.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ NewMilestone</code>( [<var class="Arg">list</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>The <code class="func">NewMilestone</code> function creates a new milestone. Its argument is a list of targets, which must be a list of integers and/or strings. If omitted, the list defaults to <code class="code">[0]</code>.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ContributeToMilestone</code>( <var class="Arg">milestone</var>, <var class="Arg">target</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>The <code class="func">ContributeToMilestone</code> milestone function contributes the specified target to the milestone. Once all targets have been contributed to a milestone, it has been achieved.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ AchieveMilestone</code>( <var class="Arg">milestone</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>The <code class="func">AchieveMilestone</code> function allows a program to achieve a milestone in a single step without adding individual targets to it. This is most useful in conjunction with the default value for <code class="func">NewMilestone</code> (<a href="chap1_mj.html#X80CB3247854A46E4"><span class="RefLink">1.6-1</span></a>), e.g.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ IsMilestoneAchieved</code>( <var class="Arg">milestone</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">IsMilestoneAchieved</code> tests explicitly if a milestone has been achieved. It returns <code class="keyw">true</code> on success, <code class="keyw">false</code> otherwise.</p>
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
