RunAsynchronously (Daemon subroutine)

Run commands on the Daemon thread asynchronously (Daemon class)

RunAsynchronously is a member of the Daemon class

This callable method runs on the daemon thread the command or set of commands specified by its first argument. Unlike the Run method, this method returns immediately and the thread issuing the RunAsynchronously method can run in parallel with the daemon thread.

Syntax

daemon:RunAsynchronously( commands, [[Input=] object]) Throws DaemonLost, IncorrectDaemonState

Syntax terms

%daem

A previously defined Daemon object.

command

A string or Stringlist that is the required command or the set of commands executed by the daemon.

%inputObj

The object passed to the daemon method object. This optional argument is passed by deep copy and not by reference, so %inputObj must be deep copyable, as described in :hdref refid=copying.. The passed object can be retrieved by the daemon thread using the GetInputObject Daemon function).

Exceptions

This subroutine can throw the following exceptions:

DaemonLost

If the daemon object 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 the RunAsynchronously method was invoked. This exception will only be thrown in Sirius Mods Version 7.2 and later.

Usage notes

• RunAsynchronously was introduced in Sirius Mods Version 7.0.
• 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.
• This is an example RunAsynchronously call:

  %daem:runAsynchronously(%list2, %x)
  

• After a RunAsynchronously method, the daemon thread is considered to be running asynchronously until a WaitAsynchronous (Daemon function) 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, methods that require interaction with the daemon thread cause request cancellation. These methods include Run, RunAsynchronously, RunIndependently, Open, and LastCommandErrorCount.
• The WaitAsynchronous method can be 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 :hdref refid=workdae., RunAsynchronously's Stringlist 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 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. 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.

See also

Daemon class	List of Daemon methods	Daemon methods syntax
Notation conventions for methods