New (Daemon constructor): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (misc cleanup)
 
(24 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{Template:Daemon:New subtitle}}
{{Template:Daemon:New subtitle}}
New is a member of the [[Daemon class]]
This method creates a new Daemon object instance. It has two, optional, arguments.


==Syntax==
==Syntax==
{{Template:Daemon:New syntax}}
{{Template:Daemon:New syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%daem</th>
<tr><th>%daemon</th>
<td>A previously defined Daemon object. </td></tr>
<td>A <var>[[Daemon class|Daemon]]</var> object. </td></tr>
<tr><th>CopyGlobals=bool</th>
 
<td>An optional, NameRequired parameter whose value is a Boolean enumeration: valid values are <tt>True</tt> and <tt>False</tt>.  
<tr><th><var>[%(Daemon):]</var></th>
The default is <tt>False</tt>: do not copy the existing global variable information from the master thread; use default GTBL-creation settings for the daemon.  
<td>The optional class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>. See [[#Usage notes|Usage notes]], below, for more information about invoking a <var>Daemon</var> <var>Constructor</var>.</td></tr>
If set to <tt>True</tt>:<ul> <li>The GTBL server table is set to the same size on the daemon as it is on the master thread. <li>The GTBLHASH and GTBLPCT parameters on the daemon thread are set to the same value as on the master thread. <li>Only unstructured globals (globals created by $setg or $getg) and Perm Global Images in the master thread GTBL are copied to the daemon (Global Foundsets/Lists, Global Screens, and any Temp Global items are '''not''' copied). </ul> </td></tr>
 
<tr><th>Transactional=bool</th>
<tr><th><var>CopyGlobals</var></th>
<td>An optional, NameRequired parameter whose value is a Boolean enumeration: valid values are <tt>True</tt> and <tt>False</tt>. If set to <tt>True</tt>, the daemon is transactional (see [[Daemon class]]), and the master and daemon threads share a single updating transaction. If set to <tt>False</tt>, the default, the daemon is non-transactional.  
<td>An optional, [[Methods#Named parameters|name required]] parameter whose value is a <var>[[Boolean enumeration]]</var>.  
This parameter is new as of ''[[Sirius Mods]]'' Version 6.8.</td></tr>
The default is <code>False</code>: do not copy the existing global variable information from the master thread; use default GTBL-creation settings for the daemon.
If set to <code>True</code>:
<ul>
<li>The GTBL server table is set to the same size on the daemon as it is on the master thread. </li>
 
<li>The <var>GTBLHASH</var> and <var>GTBLPCT</var> parameters on the daemon thread are set to the same values as on the master thread. </li>
 
<li>Only unstructured globals (globals created by <var>[[$Setg]]</var> or <var>[[$Getg]]</var>) and permanent global Images in the master thread GTBL are copied to the daemon (global foundsets/lists, global Screens, and any temporary global items are <b><i>not</i></b> copied). </li>
</ul></td></tr>
 
<tr><th><var>Transactional</var></th>
<td>An optional, name required, parameter whose value is a <var>Boolean</var> enumeration.
<ul>
<li>If set to <var>True</var>, the daemon is [[Daemon class#Transactional daemons|transactional]], with the master and daemon threads share a single updating transaction. </li>
<li>If set to <var>False</var>, the default, the daemon is non-transactional. </li>
</ul></td></tr>
 
<tr><th><var>OpenAll</var></th>
<td>An optional, name required, parameter whose value is a <var>Boolean</var> enumeration. If set to <code>True</code>, the daemon thread opens all files and groups that are open on the master thread. The files and groups are opened with the same privileges as on the master thread. Any temporary groups open on the master thread are also recreated on the Daemon thread and then opened.
<p>
This parameter is new as of <var class="product">Sirius Mods</var> Version 8.1. </p></td></tr>
</table>
</table>


==Exceptions==
==Exceptions==
This subroutine can throw the following exception:
This subroutine can throw the following exceptions:<dl>
<table class="syntaxTable">
<tr><th><var>[[NoFreeDaemons_class|NoFreeDaemons]]</var></th>
<dt>NoFreeDaemons  
<td>If there are no daemon threads available to service the object, a <var>NoFreeDaemons</var> exception is thrown. </td></tr>
<dd>If there are no daemon threads available to service the object, a [[NoFreeDaemons exception]] is thrown. This exception will only be thrown in ''[[Sirius Mods]]'' Version 7.2 and later.</dl>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>As described in [[Object variables#Using New or other Constructors|Using New or other Constructors]], <var>New</var> can be invoked with no object, with an explicit class name, or with an object variable in the class, even if that object is <var>Null</var>:
<li>The New method not only creates a Daemon object in the user tables, but it also finds a free sdaemon thread and dedicates it to the issuing user. If no sdaemon threads are available, the request is cancelled.  
<p class="code">%daemon = new
<li>The number of daemons allowed per master thread is limited by the MAXDAEM system parameter, whose default value is 1.  
 
<li>If you specify <tt>CopyGlobals=True</tt>, and if there is insufficient server space (say, if daemons start out with very big tables, except for GTBL, and the master has a very big GTBL), the daemon fails during initialization.</ul>
%daemon = %(Daemon):new
 
%daemon = %daemon:new
</p></li>
 
<li><var>New</var> not only creates a <var>Daemon</var> object in the user tables, but it also finds a free sdaemon thread and dedicates it to the issuing user. If no sdaemon threads are available, the request is cancelled.</li>
 
<li>The number of daemons allowed per master thread is limited by the <var>[[MAXDAEM parameter|MAXDAEM]]</var> system parameter, whose default value is 1.</li>
 
<li>If you specify <code>CopyGlobals=True</code>, and if there is insufficient server space (say, if daemons start out with very big tables, except for GTBL, and the master has a very big GTBL), the daemon fails during initialization.</li>
 
<li>Even files opened as part of the subsystem being run by the master thread are opened on a daemon thread when <code>OpenAll=True</code> is specified.</li>
 
<li>Opening a lot of files via <code>OpenAll=True</code> is more efficient than opening the files individually with the <var>[[Open (Daemon subroutine)|Open]]</var> method.</li>
 
<li>If LFTBL on the daemon thread is not enough to allow opening all the groups to be opened by <code>OpenAll=True</code>, the daemon thread issues an error message and logs off, and the <var>New</var> method fails.</li>
 
<li>If you want to use the master thread's open temp groups on the daemon thread, using OpenAll keeps you from having to recreate the temp groups on the Daemon thread.</li>
</ul>


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

Latest revision as of 16:02, 24 February 2015

Create a new Daemon (Daemon class)


Syntax

%daemon = [%(Daemon):]New[( [CopyGlobals= boolean], [Transactional= boolean], - [OpenAll= boolean])] Throws MaxDaemExceeded, NoFreeDaemons, DaemonLost

Syntax terms

%daemon A Daemon object.
[%(Daemon):] The optional class name in parentheses denotes a Constructor. See Usage notes, below, for more information about invoking a Daemon Constructor.
CopyGlobals An optional, name required parameter whose value is a Boolean enumeration.

The default is False: do not copy the existing global variable information from the master thread; use default GTBL-creation settings for the daemon. If set to True:

  • The GTBL server table is set to the same size on the daemon as it is on the master thread.
  • The GTBLHASH and GTBLPCT parameters on the daemon thread are set to the same values as on the master thread.
  • Only unstructured globals (globals created by $Setg or $Getg) and permanent global Images in the master thread GTBL are copied to the daemon (global foundsets/lists, global Screens, and any temporary global items are not copied).
Transactional An optional, name required, parameter whose value is a Boolean enumeration.
  • If set to True, the daemon is transactional, with the master and daemon threads share a single updating transaction.
  • If set to False, the default, the daemon is non-transactional.
OpenAll An optional, name required, parameter whose value is a Boolean enumeration. If set to True, the daemon thread opens all files and groups that are open on the master thread. The files and groups are opened with the same privileges as on the master thread. Any temporary groups open on the master thread are also recreated on the Daemon thread and then opened.

This parameter is new as of Sirius Mods Version 8.1.

Exceptions

This subroutine can throw the following exception:

NoFreeDaemons If there are no daemon threads available to service the object, a NoFreeDaemons exception is thrown.

Usage notes

  • As described in Using New or other Constructors, New can be invoked with no object, with an explicit class name, or with an object variable in the class, even if that object is Null:

    %daemon = new %daemon = %(Daemon):new %daemon = %daemon:new

  • New not only creates a Daemon object in the user tables, but it also finds a free sdaemon thread and dedicates it to the issuing user. If no sdaemon threads are available, the request is cancelled.
  • The number of daemons allowed per master thread is limited by the MAXDAEM system parameter, whose default value is 1.
  • If you specify CopyGlobals=True, and if there is insufficient server space (say, if daemons start out with very big tables, except for GTBL, and the master has a very big GTBL), the daemon fails during initialization.
  • Even files opened as part of the subsystem being run by the master thread are opened on a daemon thread when OpenAll=True is specified.
  • Opening a lot of files via OpenAll=True is more efficient than opening the files individually with the Open method.
  • If LFTBL on the daemon thread is not enough to allow opening all the groups to be opened by OpenAll=True, the daemon thread issues an error message and logs off, and the New method fails.
  • If you want to use the master thread's open temp groups on the daemon thread, using OpenAll keeps you from having to recreate the temp groups on the Daemon thread.

See also