Programmer Guide/Shell Items/Instance/SET INSTANCE: Difference between revisions

From STX Wiki
Jump to navigationJump to search
(initial import)
 
 
(10 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
==SET INSTANCE==
{{Instance Item}}


See [[Programmer Guide/Shell Items/Instance/INSTANCE Item Attributes|INSTANCE Item Attributes]] for a list of instance item attributes.
===Calling a member function===
 
<code>SET <var>instance function</var> [<var>arguments</var>]</code>


<code>SET <var>instance function</var> [<var>arguments</var>]</code>
Call the member function <var>function</var> of the instance. The function must be a member of the instance's class or of one of its base classes (searched in reverse order).
Call the member function <var>function</var> of the instance. The function must be a member of the instance's class or of one of its base classes (searched in reverse order).


<code>SET <var>instance class</var>::<var>function</var> [<var>arguments</var>]</code>
<code>SET <var>instance class</var>::<var>function</var> [<var>arguments</var>]</code>
 
Call the member function <var>function</var> of class <var>class</var>. The class must be a base class of <var>instance</var>. This call style should be used to call an overridden base-class member function (i.e. reverse search for member function is not performed).
Call the member function <var>function</var> of class <var>class</var>. The class must be a base class of <var>instance</var>. This call style should be used to call an overridden base-class member function (i.e. reverse search for member function is not performed).


<code>SET <var>instance</var> ::<var>function</var> [<var>arguments</var>]</code>
<code>SET <var>instance</var> ::<var>function</var> [<var>arguments</var>]</code>
 
Call a member function of the parent class without specifying the name of the parent class.
To call a member function of the parent class without specifying the name of the parent class, the following short command format can be used.
 
On entry into a member function, the following variables are defined:<code>#MAC</code> name of macro (= name of class)
<code>#THIS</code> name of the instance item
<code>#ARGV</code> arguments passed to the member function====LOCK====
 
<code>SET <var>instance</var> LOCK</code>
 
Lock the instance access. If a instance is locked, only the shell which locked it has access to its content. The instance must be unlocked after finishing the 'critical' processing section.
 
====TRYLOCK====
 
<code>SET <var>instance</var> TRYLOCK [ <var>timeout</var> ] [ /S ]</code>
 
Try to lock the instance item <var>instance</var>. If no timeout is specified, <code>TRYLOCK</code> returns immediately. If the caller already *holds* the lock, <code>TRYLOCK</code> will fail immediately. This makes sense because, since the caller is the owner, it cannot release it whilst its waiting.
 
;<var>timeout</var>
 
:If specified, <code>TRYLOCK</code> will try to get a lock once per millisecond until it is either successful, or <var>timeout</var> milliseconds have elapsed.


;<var>/S</var>


:If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
On entry into a member function, the following variables are defined:
* <code>#MAC</code> name of macro (= name of class)
* <code>#THIS</code> name of the instance item
* <code>#ARGV</code> arguments passed to the member function


Return Codes:
==Locking / Unlocking Instance Items==


<code>0</code> - an unlocked instance has been successfully locked.
The use of '''lock/unlock''' is only important, if an instance item is (or may be) used by more than one thread. In {{STX}} shells, spu items and display item are running in own thread.
<code>381</code> - Error: if the instance could not be locked due to it being locked by someone else.
<code>382</code> - Warning: identical to <code>381</code>, except that this returned when the /S flag is specified.
<code>383</code> - Error: if the instance could not be locked due to it being locked by the caller.
<code>384</code> - Warning: identical to <code>383</code>, except that this returned when the /S flag is specified.


Example:
SET <var>inst</var> LOCK
Lock the instance item <var>inst</var>. The execution of the calling shell is stopped, until the item can be locked. If locked, only the shell which locked it has access to the item until it is explicitly unlocked with the command <code>UNLOCK</code>. Always beware deadlocks.


"<code>SET $#instance TRYLOCK 5000</code>" will try hard to lock the instance. If it does not succeed within 5000ms (i.e., five seconds), it will fail - but it will not fail earlier.


The <code>TRYLOCK</code> command is intended for safe multithreading without race conditions occurring====UNLOCK====
SET <var>inst</var> LOCK <var>timeout</var>
Try to lock the instance item <var>inst</var>, but wait only the specified time. This command returns '''0''' (success) if the lock request was successful within the timeout, and a non-zero error code if not. If the caller already ''holds'' the lock, the command will fail immediately. This makes sense because, since the caller is the owner, it cannot release it whilst its waiting. The argument <var>timeout</var> specifies the maximum lock-timeout in milliseconds and must be a number greater than zero.


<code>SET <var>instance</var> UNLOCK</code>


Unlock instance access.
SET <var>inst</var> UNLOCK
Unlock the instance item <var>inst</var>. '''Note''': Its very important that for each successful <code>LOCK</code> an <code>UNLOCK</code> is called!

Latest revision as of 15:29, 28 January 2016

Instance Item
NEW SET ATTRIBUTES

Calling a member function

SET instance function [arguments]

Call the member function function of the instance. The function must be a member of the instance's class or of one of its base classes (searched in reverse order). 

SET instance class::function [arguments]

Call the member function function of class class. The class must be a base class of instance. This call style should be used to call an overridden base-class member function (i.e. reverse search for member function is not performed). 

SET instance ::function [arguments]

Call a member function of the parent class without specifying the name of the parent class.


On entry into a member function, the following variables are defined:

  • #MAC name of macro (= name of class)
  • #THIS name of the instance item
  • #ARGV arguments passed to the member function

Locking / Unlocking Instance Items

The use of lock/unlock is only important, if an instance item is (or may be) used by more than one thread. In STx shells, spu items and display item are running in own thread. 

SET inst LOCK

Lock the instance item inst. The execution of the calling shell is stopped, until the item can be locked. If locked, only the shell which locked it has access to the item until it is explicitly unlocked with the command UNLOCK. Always beware deadlocks. 


SET inst LOCK timeout

Try to lock the instance item inst, but wait only the specified time. This command returns 0 (success) if the lock request was successful within the timeout, and a non-zero error code if not. If the caller already holds the lock, the command will fail immediately. This makes sense because, since the caller is the owner, it cannot release it whilst its waiting. The argument timeout specifies the maximum lock-timeout in milliseconds and must be a number greater than zero. 


SET inst UNLOCK

Unlock the instance item inst. Note: Its very important that for each successful LOCK an UNLOCK is called!

Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Shell_Items/Instance/SET_INSTANCE&oldid=8769"

Navigation menu

Personal tools