RunAsynchronously (Daemon subroutine)
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. |
| 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 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. 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 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 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.
Examples
%daem:runAsynchronously(%list2, %x)