WaitAsynchronous (Daemon function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(16 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Template:Daemon:WaitAsynchronous subtitle}}
{{Template:Daemon:WaitAsynchronous subtitle}}


WaitAsynchronous is a member of the [[Daemon class]]
This [[Notation conventions for methods#Callable methods|callable]] method waits for the completion of the <var>[[RunAsynchronously (Daemon subroutine)|RunAsynchronously]]</var> or <var>[[ContinueAsynchronously (Daemon subroutine)|ContinueAsynchronously]]</var> processing on a daemon thread, and it retrieves various outputs from those methods.
 
This callable method waits for the completion of the commands issued on a daemon thread by the [[RunAsynchronously (Daemon function)]], and it retrieves various outputs from those commands.


==Syntax==
==Syntax==
{{Template:Daemon:WaitAsynchronous syntax}}
{{Template:Daemon:WaitAsynchronous syntax}}
===Syntax terms===
===Syntax terms===
<dl>
<table class="syntaxTable">
<dt>%strL
<tr><th>%sl</th>
<dd>If specified, a Stringlist object that contains the terminal output from the command or commands run on the daemon thread.  
<td>If specified, a <var>Stringlist</var> object that contains the terminal output from the command or commands run on the daemon thread. </td></tr>
<dt>%daem
<dd>A previously defined Daemon object.
<dt>%outputObj
<dd>The object returned from the daemon method object by the [[ReturnObject(Daemon function)]] invoked on the daemon thread. This optional argument is passed by deep copy and not by reference, so '''%outputObj''' must be deep copyable, as described in [[Copying objects]]. The object set to %outputObj is the object passed by the daemon thread using the [[ReturnObject(Daemon function)]].
 
Because '''%outputObj''' is an output variable, it cannot itself be contained inside an object: that is, it must be a local or a common %variable.


<dt>
<tr><th>daemon</th>
<b>Info=</b>%infoObj
<td>A <var>Daemon</var> object. </td></tr>
<dd>An optional, name required parameter that indicates a second output object returned from the daemon method object by the [[ReturnInfoObject(Daemon function)]] invoked on the daemon thread. The object set to %infoObj is the object passed by the daemon thread using the ReturnInfoObject method.  


This optional argument is passed by deep copy and not by reference, so '''%infoObj''' must be deep copyable, as described in [[Copying objects]].  
<tr><th><var>Output</var></th>
<td>An output %variable which is set to the object returned by the daemon thread using the <var>[[ReturnObject (Daemon subroutine)|ReturnObject]]</var> subroutine invoked on the daemon thread. This object is set by deep copy and not by reference, so the class of <var class="term">object</var> must be deep copyable, as described in [[Copying objects|"Copying objects"]].
<p>Because <var class="term">object</var> is an output variable, it cannot itself be contained inside an object: that is, it must be a local or a common %variable. </p></td></tr>


Because '''%infoObj''' is an output variable, it cannot itself be contained inside an object: that is, it must be a local or a common %variable.</dl>
<tr><th><var>Info</var></th>
<td>An optional, name required argument that indicates a second output %variable which is set to the object returned by the daemon thread using the <var>[[ReturnInfoObject (Daemon subroutine)|ReturnInfoObject]]</var> subroutine invoked on the daemon thread. This object is set by deep copy and not by reference, so the class of this argument must be deep copyable.
<p>Because this is an output argument, it cannot itself be contained inside an object: that is, it must be a local or a common %variable.</p></td></tr>
</table>


==Exceptions==
==Exceptions==
   
   
This subroutine can throw the following exceptions:
This subroutine can throw the following exception:


<dl>
<table class="syntaxTable">
<dt>DaemonLost  
<tr><th><var>[[DaemonLost class|DaemonLost]]</var></th>
<dd>If the daemon object is lost (probably restarted), a DaemonLost exception is thrown. This exception will only be thrown in ''[[Sirius Mods]]''.
<td>If the daemon object is lost (probably restarted), a <var>DaemonLost</var> exception is thrown. This exception will only be thrown in <var class="product">Sirius Mods</var> version 7.2 and later. </td></tr>
</dl>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
   
   
<li>WaitAsynchronous was introduced in ''[[Sirius Mods]]'' Version 7.0.  
<li><var>WaitAsynchronous</var> was introduced in <var class="product">Sirius Mods</var> version 7.0.  
<li>If WaitAsynchronous is issued against a daemon object that is not currently running asynchronously (RunAsynchronously was issued against it), the request is canceled. Note that this does not mean that the daemon must actually still be running -- if the daemon thread has run all the commands in the RunAsynchronously call, not only is WaitAsynchronous allowed, it is required before anything else can be done with the daemon. And, in any case, it's the only way of retrieving the outputs from the asynchronous request.
<li>If <var>WaitAsynchronous</var> is issued against a <var>Daemon</var> object that is not currently running asynchronously (that is, if <var>RunAsynchronously</var> was not issued against it), the request is canceled. Note that this does not mean that the <var>Daemon</var> must actually still be running &mdash; if the daemon thread has run all the commands in the <var>RunAsynchronously</var> call, not only is <var>WaitAsynchronous</var> allowed, it is required before anything else can be done with the <var>Daemon</var>. And, in any case, it's the only way of retrieving the outputs from the asynchronous request.


<li>This is an example WaitAsynchronous call:
<li>This is an example <var>WaitAsynchronous</var> call:
<pre>
<p class="code">%daem:runAsynchronously(%commands)
%daem:runAsynchronously(%commands)
...
...
%strlist = %daem:waitAsynchronous(%list2)
%strlist = %daem:waitAsynchronous(%list2)
</pre>
</p>
   
   
<li>The output Stringlist and parameters from WaitAsynchronous are identical to the output Stringlist and parameters for the Run method, so see [[Daemon class]]. for more information on and examples of output Stringlists and objects.
<li>The output <var>Stringlist</var> and parameters from <var>WaitAsynchronous</var> are identical to the output <var>Stringlist</var> and parameters for the <var>[[Run (Daemon function)|Run]]</var> method, so see [[Daemon class|"Daemon class"]] for more information on and examples of output <var>Stringlists</var> and objects.
<li>The inputs and outputs from the combination of RunAsynchronously and WaitAsynchronous are identical to the inputs and outputs from the Run method. 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.  
<li>The inputs and outputs from the combination of <var>RunAsynchronously</var> and <var>WaitAsynchronous</var> are identical to the inputs and outputs from the <var>Run</var> method. As such, it should be a relatively simple task to split a <var>Run</var> invocation into <var>RunAsynchronously</var> and <var>WaitAsynchronous</var> invocations, 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:
For example, if a request has the following statements:


<pre>
<p class="code">%out1 = %daem1:run(%cmds1, %inobj1, %outobj1)
%out1 = %daem1:run(%cmds1, %inobj1, %outobj1)
%out2 = %daem2:run(%cmds2, %inobj2, %outobj2)
%out2 = %daem2:run(%cmds2, %inobj2, %outobj2)
</pre>
</p>


The statements can be easily split up into the following, and the processing on the two daemons would be performed in parallel with each other:
The statements can be easily split up into the following, and the processing on the two <var>Daemon</var>s would be performed in parallel with each other:


<pre>
<p class="code">%daem1:runAsynchronously(%cmds1, %inobj1)
%daem1:runAsynchronously(%cmds1, %inobj1)
%daem2:runAsynchronously(%cmds2, %inobj2)
%daem2:runAsynchronously(%cmds2, %inobj2)
%out1 = %daem1:waitAsynchronous(%outobj1)
%out1 = %daem1:waitAsynchronous(%outobj1)
%out2 = %daem2:waitAsynchronous(%outobj2)
%out2 = %daem2:waitAsynchronous(%outobj2)
</pre>
</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.


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.</ul>
<li>For more information about asynchronous daemons, see [[Daemon class#Asynchronous and Independent daemons|"Asynchronous and Independent daemons"]].
</ul>


==See also==
==See also==
{{Template:Daemon:WaitAsynchronous footer}}
{{Template:Daemon:WaitAsynchronous footer}}

Latest revision as of 20:53, 8 July 2012

Wait for an asynchronous result (Daemon class)


This callable method waits for the completion of the RunAsynchronously or ContinueAsynchronously processing on a daemon thread, and it retrieves various outputs from those methods.

Syntax

[%sl =] daemon:WaitAsynchronous[( [[Output=] object], [Info= object])] Throws DaemonLost, IncorrectDaemonState

Syntax terms

%sl If specified, a Stringlist object that contains the terminal output from the command or commands run on the daemon thread.
daemon A Daemon object.
Output An output %variable which is set to the object returned by the daemon thread using the ReturnObject subroutine invoked on the daemon thread. This object is set by deep copy and not by reference, so the class of object must be deep copyable, as described in "Copying objects".

Because object is an output variable, it cannot itself be contained inside an object: that is, it must be a local or a common %variable.

Info An optional, name required argument that indicates a second output %variable which is set to the object returned by the daemon thread using the ReturnInfoObject subroutine invoked on the daemon thread. This object is set by deep copy and not by reference, so the class of this argument must be deep copyable.

Because this is an output argument, it cannot itself be contained inside an object: that is, it must be a local or a common %variable.

Exceptions

This subroutine can throw the following exception:

DaemonLost If the daemon object is lost (probably restarted), a DaemonLost exception is thrown. This exception will only be thrown in Sirius Mods version 7.2 and later.

Usage notes

  • WaitAsynchronous was introduced in Sirius Mods version 7.0.
  • If WaitAsynchronous is issued against a Daemon object that is not currently running asynchronously (that is, if RunAsynchronously was not issued against it), the request is canceled. Note that this does not mean that the Daemon must actually still be running — if the daemon thread has run all the commands in the RunAsynchronously call, not only is WaitAsynchronous allowed, it is required before anything else can be done with the Daemon. And, in any case, it's the only way of retrieving the outputs from the asynchronous request.
  • This is an example WaitAsynchronous call:

    %daem:runAsynchronously(%commands) ... %strlist = %daem:waitAsynchronous(%list2)

  • The output Stringlist and parameters from WaitAsynchronous are identical to the output Stringlist and parameters for the Run method, so see "Daemon class" for more information on and examples of output Stringlists and objects.
  • The inputs and outputs from the combination of RunAsynchronously and WaitAsynchronous are identical to the inputs and outputs from the Run method. As such, it should be a relatively simple task to split a Run invocation into RunAsynchronously and WaitAsynchronous invocations, 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, 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".

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=WaitAsynchronous_(Daemon_function)&oldid=9627"