Programmer Guide/Shell Items/Instance/SET INSTANCE: Difference between revisions
From STX Wiki
< Programmer Guide | Shell Items | Instance
Jump to navigationJump to search
No edit summary |
No edit summary |
||
| Line 5: | Line 5: | ||
<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). | |||
<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. | |||
On entry into a member function, the following variables are defined: | On entry into a member function, the following variables are defined: | ||
| Line 23: | Line 22: | ||
===LOCK=== | ===LOCK=== | ||
<code>SET <var>instance</var> LOCK</code> | <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. | 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=== | ===TRYLOCK=== | ||
<code>SET <var>instance</var> TRYLOCK [ <var>timeout</var> ] [ /S ]</code> | <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. | 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. | ||
| Line 42: | Line 39: | ||
Return Codes: | Return Codes: | ||
:<code>0</code> - an unlocked instance has been successfully locked. | |||
<code>0</code> - an unlocked instance has been successfully locked. | :<code>381</code> - Error: if the instance could not be locked due to it being locked by someone else. | ||
<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>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>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. | ||
<code>384</code> - Warning: identical to <code>383</code>, except that this returned when the /S flag is specified. | |||
Example: | Example: | ||
"<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. | "<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 | The <code>TRYLOCK</code> command is intended for safe multithreading without race conditions occurring | ||
Revision as of 16:03, 22 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:
#MACname of macro (= name of class)#THISname of the instance item#ARGVarguments passed to the member function
LOCK
SET instance LOCK
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
SET instance TRYLOCK [ timeout ] [ /S ]
Try to lock the instance item instance. If no timeout is specified, TRYLOCK returns immediately. If the caller already *holds* the lock, TRYLOCK will fail immediately. This makes sense because, since the caller is the owner, it cannot release it whilst its waiting.
- timeout
- If specified,
TRYLOCKwill try to get a lock once per millisecond until it is either successful, or timeout milliseconds have elapsed.
- /S
- If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
Return Codes:
0- an unlocked instance has been successfully locked.381- Error: if the instance could not be locked due to it being locked by someone else.382- Warning: identical to381, except that this returned when the /S flag is specified.383- Error: if the instance could not be locked due to it being locked by the caller.384- Warning: identical to383, except that this returned when the /S flag is specified.
Example:
"SET $#instance TRYLOCK 5000" 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 TRYLOCK command is intended for safe multithreading without race conditions occurring
UNLOCK
SET instance UNLOCK
Unlock instance access.
