RunAsynchronously (Daemon subroutine): Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
m (match syntax table to syntax template (will need to be redone when syntax template is fixed) tags and edits) |
||
| Line 1: | Line 1: | ||
{{Template:Daemon:RunAsynchronously subtitle}} | {{Template:Daemon:RunAsynchronously subtitle}} | ||
<var>RunAsynchronously</var> runs on the daemon thread the command or set of commands specified by its first argument. Unlike the <var>[[Run (Daemon function)|Run]]</var> method, <var>RunAsynchronously</var> returns immediately allowing the thread issuing <var>RunAsynchronously</var> to run in parallel with the daemon thread. | |||
RunAsynchronously | |||
==Syntax== | ==Syntax== | ||
| Line 9: | Line 6: | ||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>% | <tr><th>%daemon</th> | ||
<td>A previously defined Daemon object. </td></tr> | <td>A previously defined <var>[[Daemon class|Daemon]]</var> object. </td></tr> | ||
<tr><th> | <tr><th>string</th> | ||
<td>A string or Stringlist that is the required command or the set of commands executed by the daemon. </td></tr> | <td>A string or Stringlist that is the required command or the set of commands executed by the <var>daemon</var>.</td></tr> | ||
<tr><th> | <tr><th>inputObj</th> | ||
<td>The object passed to | <td>The object passed to <var>daemon</var> object. This optional argument is passed by deep copy and not by reference, so <var class="term">inputObj</var> must be deep copyable, as described in: [[Copying objects|"Copying objects"]]. The passed object can be retrieved by the daemon thread using the <var>[[GetInputObject_(Daemon_subroutine)|GetInputObject]]</var>.</td></tr> | ||
</table> | </table> | ||
==Exceptions== | ==Exceptions== | ||
<var>RunAsynchronously</var> can throw the following exceptions: | |||
<dl> | <dl> | ||
<dt>DaemonLost | <dt><var>[[DaemonLost_class|DaemonLost]]</var> | ||
<dd>If | <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. This exception will only be thrown in <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.2 and later. | ||
</dl> | </dl> | ||
==Usage notes== | ==Usage notes== | ||
<ul> | <ul> | ||
<li>RunAsynchronously | <li>Issuing <var>RunAsynchronously</var> against a transactional <var>daemon</var> results in request cancellation. | ||
< | <li>If the <var>daemon</var> thread and its <var>daemons</var> hold record locks that conflict with the parent thread's family (excluding the <var>daemon</var> thread and its <var>daemons</var>), <var>RunAsynchronously</var> results in request cancellation. | ||
<li>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. | <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> | <li>While the <var>daemon</var> thread is running asynchronously, any methods that require interaction with the <var>daemon</var> thread 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><var>[[WaitAsynchronous (Daemon function)|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>As described in: [[Daemon class#Working with Daemonobjects|"Working with Daemon objects"]], <var>RunAsynchronously's</var> <var>String</var> argument can pass multiple commands to the <var>daemon</var>. | ||
<li>See [[Daemon class|"Daemon class"]] for more information about passing commands and objects to a daemon -- the passing of objects and commands to daemons is identical whether the method is a <var>[[Run_(Daemon_function)|Run]]</var> or <var>RunAsynchronously</var>. | |||
<li>If the <var>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>While the daemon thread is running asynchronously, methods that require interaction with the daemon thread cause request cancellation. These methods include Run, RunAsynchronously, RunIndependently, Open, and LastCommandErrorCount. | <li>The inputs and outputs from the combination of <var>RunAsynchronously</var> and <var>[[WaitAsynchronous (Daemon function)|WaitAsynchronous]]</var> are identical to the inputs and outputs from <var>[[Run_(Daemon_function)|Run]]</var>. As such, it should be a relatively simple task to split a <var>[[Run_(Daemon_function)|Run]]</var> into a <var>RunAsynchronously</var> and <var>[[WaitAsynchronous (Daemon function)|WaitAsynchronous]]</var>, allowing the daemon processing to be performed in parallel with parent thread processing or the processing on another daemon thread. | ||
<li> | <p>For example, if a request has the following statements:</p> | ||
<li>As described in : | <p class="code">%out1 = %daem1:run(%cmds1, %inobj1, %outobj1) | ||
<li>See [[Daemon class]] for more information about passing commands and objects to a daemon -- the passing of objects and commands to daemons is identical whether the method is a Run or RunAsynchronously. | |||
<li>If the daemon object associated with an asynchronously running daemon is discarded either explicitly or implicitly | |||
<li>The inputs and outputs from the combination of RunAsynchronously and WaitAsynchronous are identical to the inputs and outputs from | |||
For example, if a request has the following statements: | |||
<p class="code" | |||
%out2 = %daem2:run(%cmds2, %inobj2, %outobj2) | %out2 = %daem2:run(%cmds2, %inobj2, %outobj2) | ||
</ | </p> | ||
<p>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:</p> | |||
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: | <p class="code">%daem1:runAsynchronously(%cmds1, %inobj1) | ||
<p class="code" | |||
%daem2:runAsynchronously(%cmds2, %inobj2) | %daem2:runAsynchronously(%cmds2, %inobj2) | ||
%out1 = %daem1:waitAsynchronous(%outobj1) | %out1 = %daem1:waitAsynchronous(%outobj1) | ||
%out2 = %daem2:waitAsynchronous(%outobj2) | %out2 = %daem2:waitAsynchronous(%outobj2) | ||
</ | </p> | ||
<p>Note that this will buy nothing if the requests are CPU-intensive and the request is not running with AMPSUBS>0 (requires <car class="product">MP/204</var>). Note also that if the <var>daemons</var> 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 <var>daemon</var>, such a split is not feasible for transactional <var>daemons</var>.</p> | |||
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. | <li><var>RunAsynchronously</var> was introduced in <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.0. | ||
</ul> | </ul> | ||
==Examples== | |||
<ol><li><p class="code">%daem:runAsynchronously(%list2, %x) | |||
</p> | |||
</ol> | |||
==See also== | ==See also== | ||
{{Template:Daemon:RunAsynchronously footer}} | {{Template:Daemon:RunAsynchronously footer}} | ||
Revision as of 04:53, 14 March 2011
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. |
|---|---|
| string | A string or Stringlist that is the required command or the set of commands executed by the daemon. |
| inputObj | The object passed to daemon object. This optional argument is passed by deep copy and not by reference, so inputObj 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 exceptions:
- 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. This exception will only be thrown in "Sirius Mods" Version 7.2 and later.
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 the daemon thread 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", RunAsynchronously's String argument can pass multiple commands to the daemon.
- See "Daemon class" for more information about passing commands and objects to a daemon -- the passing of objects and commands to daemons is identical whether the method is a Run or RunAsynchronously.
- 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 <car class="product">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.
- RunAsynchronously was introduced in "Sirius Mods" Version 7.0.
Examples
%daem:runAsynchronously(%list2, %x)