RunAsynchronously (Daemon subroutine)

From m204wiki
Revision as of 20:56, 22 May 2012 by JAL2 (talk | contribs) (→‎Usage notes)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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)

See also