Programmer Guide/Shell Items/Instance/SET INSTANCE - Revision history

Toni: /* Calling a member function */

2016-01-28T14:29:14Z

Calling a member function

← Older revision		Revision as of 16:29, 28 January 2016
Line 6:		Line 6:
	<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>

Toni: /* Locking / Unlocking Instance Items */

2016-01-28T14:20:46Z

Locking / Unlocking Instance Items

← Older revision		Revision as of 16:20, 28 January 2016
Line 22:		Line 22:
	==Locking / Unlocking Instance Items==		==Locking / Unlocking Instance Items==

	The use of '''lock/unlock''' is only important, if ~~a file~~ item is (or may be) used by more than one thread. In {{STX}} shells, spu items and display item are running in own thread.		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 <var>inst</var> LOCK		SET <var>inst</var> LOCK

Toni: /* Locking / Unlocking Instance Items */

2016-01-28T14:07:18Z

Locking / Unlocking Instance Items

← Older revision		Revision as of 16:07, 28 January 2016
Line 33:		Line 33:

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

Toni at 14:06, 28 January 2016

2016-01-28T14:06:08Z

← Older revision		Revision as of 16:06, 28 January 2016
Line 20:		Line 20:
	* <code>#ARGV</code> arguments passed to the member function		* <code>#ARGV</code> arguments passed to the member function

	==~~=LOCK=~~==		==Locking / Unlocking Instance Items==

	~~<code>SET <var>instance<~~/~~var> LOCK</code>~~		The use of '''lock/unlock''' is only important, if a file item is (or may be) used by more than one thread. In {{STX}} shells, spu items and display item are running in own thread.
	~~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 <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 <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>		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.

	~~: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>		SET <var>inst</var> UNLOCK
			Unlock the instance item <var>inst</var>. '''Note''': Its very important that for each successful LOCK an UNLOCK is called!
	~~:If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.~~

	~~Return Codes:~~
	~~:<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~~>~~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:~~

	~~"<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~~===~~

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

	~~Unlock instance access.~~

Toni at 14:03, 22 January 2016

2016-01-22T14:03:38Z

← Older revision		Revision as of 16:03, 22 January 2016
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).

	~~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:		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

Toni at 14:01, 22 January 2016

2016-01-22T14:01:39Z

← Older revision		Revision as of 16:01, 22 January 2016
Line 4:		Line 4:
	===Calling a member function===		===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>

	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.		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)		On entry into a member function, the following variables are defined:
	<code>#THIS</code> name of the instance item		* <code>#MAC</code> name of macro (= name of class)
	<code>#ARGV</code> arguments passed to the member function		* <code>#THIS</code> name of the instance item
			* <code>#ARGV</code> arguments passed to the member function

	===LOCK===		===LOCK===

Toni at 14:00, 22 January 2016

2016-01-22T14:00:19Z

← Older revision		Revision as of 16:00, 22 January 2016
Line 2:		Line 2:
	{{Instance Item}}		{{Instance Item}}

			===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).

	~~===Calling a member function===~~

	<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>

Toni at 13:59, 22 January 2016

2016-01-22T13:59:49Z

← Older revision		Revision as of 15:59, 22 January 2016
Line 53:		Line 53:
	"<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====UNLOCK====		The <code>TRYLOCK</code> command is intended for safe multithreading without race conditions occurring

			===UNLOCK===

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

	Unlock instance access.		Unlock instance access.

Toni at 13:58, 22 January 2016

2016-01-22T13:58:11Z

← Older revision		Revision as of 15:58, 22 January 2016
Line 1:		Line 1:
	{{DISPLAYTITLE:{{SUBPAGENAME}}}}		{{DISPLAYTITLE:{{SUBPAGENAME}}}}
	{{Instance Item}}		{{Instance Item}}


	<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).

			===Calling a member function===

	<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>
Line 16:		Line 19:
	On entry into a member function, the following variables are defined:<code>#MAC</code> name of macro (= name of class)		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>#THIS</code> name of the instance item
	<code>#ARGV</code> arguments passed to the member function====LOCK====		<code>#ARGV</code> arguments passed to the member function

			===LOCK===

	<code>SET <var>instance</var> LOCK</code>		<code>SET <var>instance</var> LOCK</code>
Line 22:		Line 27:
	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>

Jw at 06:11, 5 May 2015

2015-05-05T06:11:27Z

← Older revision		Revision as of 08:11, 5 May 2015
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.~~

	<code>SET <var>instance function</var> [<var>arguments</var>]</code>		<code>SET <var>instance function</var> [<var>arguments</var>]</code>