RunAsynchronously (Daemon subroutine): Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
m (→Usage notes) |
||
| (13 intermediate revisions by 2 users not shown) | |||
| Line 7: | Line 7: | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>daemon</th> | <tr><th>daemon</th> | ||
<td>A previously defined <var> | <td>A previously defined <var>Daemon</var> object. </td></tr> | ||
<tr><th> | <tr><th>commands</th> | ||
<td>A string or <var>[[Stringlist class|Stringlist]]</var> that is the | <td>A string or <var>[[Stringlist class|Stringlist]]</var> that is the command or the set of commands executed by the daemon.</td></tr> | ||
<tr><th> | <tr><th><var>Input</var></th> | ||
<td> | <td>An object passed to the <var class="term">daemon</var> object. This optional, [[Notation conventions for methods#Named parameters|name allowed]], argument is passed by deep copy and not by reference, so <var class="term">object</var> must be deep copyable, as described in [[Copying objects|"Copying objects"]]. | ||
<p> | |||
The passed object can be retrieved by the daemon thread using the <var>[[GetInputObject_(Daemon_subroutine)|GetInputObject]]</var>. </p></td></tr> | |||
</table> | </table> | ||
==Exceptions== | ==Exceptions== | ||
<var>RunAsynchronously</var> can throw the following | <var>RunAsynchronously</var> can throw the following exception: | ||
<dl> | <dl> | ||
<dt><var>[[DaemonLost_class|DaemonLost]]</var> | <dt><var>[[DaemonLost_class|DaemonLost]]</var> | ||
<dd>If <var>daemon</var> is lost (probably restarted), a <var>DaemonLost</var> exception is thrown. Since <var>RunAsynchronously</var> does not wait for the <var>daemon</var> thread to do anything, a <var>DaemonLost</var> exception indicates that the daemon thread was lost <b><i>before</i></b> <var>RunAsynchronously</var> was invoked | <dd>If <var class="term">daemon</var> is lost (probably restarted), a <var>DaemonLost</var> exception is thrown. Since <var>RunAsynchronously</var> does not wait for the <var>daemon</var> thread to do anything, a <var>DaemonLost</var> exception indicates that the daemon thread was lost <b><i>before</i></b> <var>RunAsynchronously</var> was invoked. | ||
</dl> | </dl> | ||
==Usage notes== | ==Usage notes== | ||
<ul> | <ul> | ||
<li>Issuing <var>RunAsynchronously</var> against a transactional | <li>Issuing <var>RunAsynchronously</var> against a [[Daemon class#Transactional daemons|transactional daemon]] results in request cancellation. | ||
<li>If the <var>daemon</var> thread and its | <li>If the <var class="term">daemon</var> thread and its daemons hold record locks that conflict with the parent thread's family (excluding the <var class="term">daemon</var> thread and its daemons), <var>RunAsynchronously</var> results in request cancellation. | ||
<li>Once started via <var>RunAsynchronously</var>, the <var>daemon</var> thread is considered to be running asynchronously until a <var>[[WaitAsynchronous (Daemon function)|WaitAsynchronous]]</var> is issued against the <var>daemon</var> object. This is the case, even if the <var>daemon</var> thread has completed processing all of the input commands. | |||
<li>While the <var>daemon</var> thread is running asynchronously, any methods that require interaction with | <li>Once started via <var>RunAsynchronously</var>, the <var class="term">daemon</var> thread is considered to be running asynchronously until a <var>[[WaitAsynchronous (Daemon function)|WaitAsynchronous]]</var> is issued against the <var class="term">daemon</var> object. This is the case, even if the <var class="term">daemon</var> thread has completed processing all of the input commands. | ||
<li><var> | |||
<li>As described in: [[Daemon class#Working with | <li>While the <var class="term">daemon</var> thread is running asynchronously, any methods that require interaction with it cause request cancellation. These methods include <var>[[Run_(Daemon_function)|Run]]</var>, <var>RunAsynchronously</var>, <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>, <var>[[Open_(Daemon_subroutine)|Open]]</var>, and <var>[[LastCommandErrorCount_(Daemon_property)|LastCommandErrorCount]]</var>. | ||
<li> | |||
<li>If the <var>daemon</var> object associated with an asynchronously running <var> | <li><var>WaitAsynchronous</var> is used to retrieve any output from the commands run via <var>RunAsynchronously</var>. This includes the terminal output and any output or info object. | ||
<li>The inputs and outputs from the combination of <var>RunAsynchronously</var> and <var> | |||
<li>As described in: [[Daemon class#Working with Daemon objects|"Working with Daemon objects"]], the <var>RunAsynchronously</var> <var class="term">commands</var> argument can pass multiple commands to the <var class="term">daemon</var> object. | |||
<li>The passing of objects and commands to daemons is identical whether the method is <var>Run</var> or <var>RunAsynchronously</var> — see [[Daemon class#Working with Daemon objects|"Working with Daemon objects"]] for more information about passing commands and objects to a <var>Daemon</var>. | |||
<li>If the <var class="term">daemon</var> object associated with an asynchronously running <var>Daemon</var> is discarded, either explicitly or implicitly, the <var>Daemon</var> thread is bumped by the parent thread. An implicit discard can happen at request end (for non-global daemon objects) or at user logout. | |||
<li>The inputs and outputs from the combination of <var>RunAsynchronously</var> and <var>WaitAsynchronous</var> are identical to the inputs and outputs from <var>Run</var>. As such, it should be a relatively simple task to split a <var>Run</var> into a <var>RunAsynchronously</var> and <var>WaitAsynchronous</var>, allowing the daemon processing to be performed in parallel with parent thread processing or the processing on another daemon thread. | |||
<p>For example, if a request has the following statements:</p> | <p>For example, if a request has the following statements:</p> | ||
<p class="code">%out1 = %daem1:run(%cmds1, %inobj1, %outobj1) | |||
%out2 = %daem2:run(%cmds2, %inobj2, %outobj2) | %out2 = %daem2:run(%cmds2, %inobj2, %outobj2) | ||
</p> | </p> | ||
| Line 43: | Line 52: | ||
%out2 = %daem2:waitAsynchronous(%outobj2) | %out2 = %daem2:waitAsynchronous(%outobj2) | ||
</p> | </p> | ||
<p>Note that this will buy nothing if the requests are CPU-intensive and the request is not running with AMPSUBS>0 (requires < | <p>Note that this will buy nothing if the requests are CPU-intensive and the request is not running with <code>AMPSUBS>0</code> (requires <var class="product">MP/204</var>). Note also that if the daemons hold or require record locks that might conflict with each other, such a split will not work. Finally, since <var>RunAsynchronously</var> is not allowed for a transactional daemon, such a split is not feasible for transactional daemons.</p> | ||
<li> | |||
<li>For more information about asynchronous daemons, see [[Daemon class#Asynchronous and Independent daemons|"Asynchronous and Independent daemons"]]. | |||
</ul> | </ul> | ||
==Examples== | ==Examples== | ||
<p class="code">%daem:runAsynchronously(%list2, %x) | |||
</p> | </p> | ||
==See also== | ==See also== | ||
{{Template:Daemon:RunAsynchronously footer}} | {{Template:Daemon:RunAsynchronously footer}} | ||
Latest revision as of 20:56, 22 May 2012
Run commands on the Daemon thread asynchronously (Daemon class)
RunAsynchronously runs on the daemon thread the command or set of commands specified by its first argument. Unlike the Run method, RunAsynchronously returns immediately allowing the thread issuing RunAsynchronously to run in parallel with the daemon thread.
Syntax
daemon:RunAsynchronously( commands, [[Input=] object]) Throws DaemonLost, IncorrectDaemonState
Syntax terms
| daemon | A previously defined Daemon object. |
|---|---|
| commands | A string or Stringlist that is the command or the set of commands executed by the daemon. |
| Input | An object passed to the daemon object. This optional, name allowed, argument is passed by deep copy and not by reference, so object must be deep copyable, as described in "Copying objects".
The passed object can be retrieved by the daemon thread using the GetInputObject. |
Exceptions
RunAsynchronously can throw the following exception:
- DaemonLost
- If daemon is lost (probably restarted), a DaemonLost exception is thrown. Since RunAsynchronously does not wait for the daemon thread to do anything, a DaemonLost exception indicates that the daemon thread was lost before RunAsynchronously was invoked.
Usage notes
- Issuing RunAsynchronously against a transactional daemon results in request cancellation.
- If the daemon thread and its daemons hold record locks that conflict with the parent thread's family (excluding the daemon thread and its daemons), RunAsynchronously results in request cancellation.
- Once started via RunAsynchronously, the daemon thread is considered to be running asynchronously until a WaitAsynchronous is issued against the daemon object. This is the case, even if the daemon thread has completed processing all of the input commands.
- While the daemon thread is running asynchronously, any methods that require interaction with it cause request cancellation. These methods include Run, RunAsynchronously, RunIndependently, Open, and LastCommandErrorCount.
- WaitAsynchronous is used to retrieve any output from the commands run via RunAsynchronously. This includes the terminal output and any output or info object.
- As described in: "Working with Daemon objects", the RunAsynchronously commands argument can pass multiple commands to the daemon object.
- The passing of objects and commands to daemons is identical whether the method is Run or RunAsynchronously — see "Working with Daemon objects" for more information about passing commands and objects to a Daemon.
- If the daemon object associated with an asynchronously running Daemon is discarded, either explicitly or implicitly, the Daemon thread is bumped by the parent thread. An implicit discard can happen at request end (for non-global daemon objects) or at user logout.
- The inputs and outputs from the combination of RunAsynchronously and WaitAsynchronous are identical to the inputs and outputs from Run. As such, it should be a relatively simple task to split a Run into a RunAsynchronously and WaitAsynchronous, allowing the daemon processing to be performed in parallel with parent thread processing or the processing on another daemon thread.
For example, if a request has the following statements:
%out1 = %daem1:run(%cmds1, %inobj1, %outobj1) %out2 = %daem2:run(%cmds2, %inobj2, %outobj2)
The statements can be easily split up into the following ones, and the processing on the two daemons would be performed in parallel with each other:
%daem1:runAsynchronously(%cmds1, %inobj1) %daem2:runAsynchronously(%cmds2, %inobj2) %out1 = %daem1:waitAsynchronous(%outobj1) %out2 = %daem2:waitAsynchronous(%outobj2)
Note that this will buy nothing if the requests are CPU-intensive and the request is not running with
AMPSUBS>0(requires MP/204). Note also that if the daemons hold or require record locks that might conflict with each other, such a split will not work. Finally, since RunAsynchronously is not allowed for a transactional daemon, such a split is not feasible for transactional daemons. - For more information about asynchronous daemons, see "Asynchronous and Independent daemons".
Examples
%daem:runAsynchronously(%list2, %x)