Programmer Guide/Shell Items/SPU - Revision history

Jw: /* SPU Item Attributes */

2015-10-23T10:38:27Z

SPU Item Attributes

← Older revision		Revision as of 12:38, 23 October 2015
Line 45:		Line 45:

	==SPU Item Attributes==		==SPU Item Attributes==
	{\|class="~~keinrahmen~~"		{\|class="einrahmen"
	!attribute/argument !!description !!values		!attribute/argument !!description !!values
	\|-		\|-

Jw: adding template

2015-05-05T06:50:49Z

adding template

← Older revision		Revision as of 08:50, 5 May 2015
Line 1:		Line 1:
	{{DISPLAYTITLE:{{SUBPAGENAME}}}}		{{DISPLAYTITLE:{{SUBPAGENAME}}}}
			{{SPU Item}}
	An SPU (''signal processing unit'') is a [[Programmer_Guide/Shell_Items\|shell item]] for controlling (software) signal processing units (SPUs). An SPU is a circuit connecting one or more [[Programmer_Guide/SPU_Reference\|Signal Processing Atom]] together. The ciruit (its SP atoms, inputs, outputs, and internal connections) is defined in a [[Programmer_Guide/Source_code#Definition_of_SPUs\|SPU section]] of a source file. This SPU source file must be loaded before the SPU item (i.e. the runtime instance of the circuit) can be created.		An SPU (''signal processing unit'') is a [[Programmer_Guide/Shell_Items\|shell item]] for controlling (software) signal processing units (SPUs). An SPU is a circuit connecting one or more [[Programmer_Guide/SPU_Reference\|Signal Processing Atom]] together. The ciruit (its SP atoms, inputs, outputs, and internal connections) is defined in a [[Programmer_Guide/Source_code#Definition_of_SPUs\|SPU section]] of a source file. This SPU source file must be loaded before the SPU item (i.e. the runtime instance of the circuit) can be created.

Line 108:		Line 109:
	\|}		\|}
	Note: All attribute names can be abbreviated to the shortest unique form.		Note: All attribute names can be abbreviated to the shortest unique form.
	~~[[Category:Shell Items]]~~
	~~[[Category:Programmer Guide]]~~

Christian: /* SPU Item Attributes */

2013-04-23T07:51:55Z

SPU Item Attributes

← Older revision		Revision as of 09:51, 23 April 2013
Line 45:		Line 45:
	==SPU Item Attributes==		==SPU Item Attributes==
	{\|class="keinrahmen"		{\|class="keinrahmen"
	!attribute !!description !!values		!attribute/argument !!description !!values
	\|-		\|-
	\|<code>!mode</code>		\|<code>!mode</code>

Christian: /* SPU Item Attributes */

2013-04-23T07:51:37Z

SPU Item Attributes

← Older revision		Revision as of 09:51, 23 April 2013
Line 49:		Line 49:
	\|<code>!mode</code>		\|<code>!mode</code>
	\| current mode of the SPU item		\| current mode of the SPU item
	\|RUN, STOP, EXIT		\|<code>RUN</code>, <code>STOP</code>, <code>EXIT</code>
	\|-		\|-
	\|<code>!nrun</code>		\|<code>!nrun</code>
	\|number of finished evaluation cycles		\|number of finished evaluation cycles
	\|≥0		\|an integer ≥0
	\|-		\|-
	\|<code>!maxrun</code>		\|<code>!maxrun</code>
	\|maximum number of ealuation cycles<BR>if equal 0, no maximum number is defined (''endless'' execution)		\|maximum number of ealuation cycles<BR>if equal 0, no maximum number is defined (''endless'' execution)
	\|≥0		\|an integer ≥0
	\|-		\|-
	\|<code>!code</code>		\|<code>!code</code>
Line 65:		Line 65:
	\|<code>!noutput</code>		\|<code>!noutput</code>
	\|number of SPU outputs		\|number of SPU outputs
	\|≥0		\|an integer ≥0
	\|-		\|-
	\|<code>!outputs</code>		\|<code>!outputs</code>
Line 71:		Line 71:
	\|		\|
	\|-		\|-
	\|<code>!output,''i''</code>		\|<code>!output, <var>i</var></code>
	\|name of the output ''i''<BR>0≤''i''<<code><var>spu</var>[!noutput]</code>		\|name of the output <var>i</var>, 0≤<var>i</var><<code><var>spu</var>[!noutput]</code>
	\|		\|
	\|-		\|-
	\|<code>!ninput</code>		\|<code>!ninput</code>
	\|number of SPU inputs		\|number of SPU inputs
	\|≥0		\|an integer ≥0
	\|-		\|-
	\|<code>!inputs</code>		\|<code>!inputs</code>
Line 83:		Line 83:
	\|		\|
	\|-		\|-
	\|<code>!input,''i''</code>		\|<code>!input, <var>i</var></code>
	\|name of the ~~output ''~~i''<BR>0≤''i''<<code><var>spu</var>[!ninput]</code>		\|name of the input <var>i</var>, 0≤<var>i</var><<code><var>spu</var>[!ninput]</code>
	\|		\|
	\|-		\|-
	\|<code>!thread</code>		\|<code>!thread</code>
	\|1 if the SPU is executed in a own thread<BR>0 if the SPU runs in the shell's thread		\|<code>1</code> if the SPU is executed in a own thread,<BR>0 if the SPU runs in the shell thread
	\|0 or 1		\|<code>0</code> or <code>1</code>
	\|-		\|-
	\|<code>!master</code>		\|<code>!master</code>
	\|1 if the SPU is the master and, otherwise 0 (slave)		\|<code>1</code> if the SPU is the master and, otherwise <code>0</code> (slave)
	\|0 or 1		\|<code>0</code> or <code>1</code>
	\|-		\|-
	\|<code>!failed</code>		\|<code>!failed</code>
	\|1 if the SPU execution has failed, otherwise 0		\|<code>1</code> if the SPU execution has failed, otherwise <code>0</code>
	\|0 or 1		\|<code>0</code> or <code>1</code>
	\|-		\|-
	\|<code>!done</code>		\|<code>!done</code>
	\|1 if the SPU execution is finished, otherwise 0<BR>~~this~~ flag can be used to determine if the execution can be continued (e.g. after a STOP or a single step) or not		\|<code>1</code> if the SPU execution is finished, otherwise <code>0</code><BR>This flag can be used to determine if the execution can be continued (e.g. after a <code>STOP</code> or a single step) or not
	\|0 or 1		\|<code>0</code> or <code>1</code>
	\|-		\|-
	\|<code>!emsg</code> or <code>!lasterror</code>		\|<code>!emsg</code> or <code>!lasterror</code>
	\|last SPU error message (for debugging)<BR>~~the~~ attribute is empty if no error ~~was reported by a SP-atom~~		\|last SPU error message (for debugging)<BR>This attribute is empty if no SPAtom had an error to report.
	\|		\|
	\|}		\|}

Christian: /* SPU Item Messages */

2013-04-23T07:36:02Z

SPU Item Messages

← Older revision		Revision as of 09:36, 23 April 2013
Line 41:		Line 41:
	This message is sent by the master SPU item when the evaluation has been stopped. The first SPU item (a.k.a. the master SPU) of a chain (if other SPUs are connected) is the only one which sends this message. The parameter <var>runs</var> is set to the number of finished evaluation cycles.		This message is sent by the master SPU item when the evaluation has been stopped. The first SPU item (a.k.a. the master SPU) of a chain (if other SPUs are connected) is the only one which sends this message. The parameter <var>runs</var> is set to the number of finished evaluation cycles.

	During execution, the SPU item also communicates with connected graph items, value items, and other SPU items, via the input-output connections. This data exchange is performed by a combination of messages and lock/unlock mechanisms. This is neither 100% secure nor stable, meaning that, occasionally, a deadlock situation may arise, leading the shell owning the circuit into ~~blocking~~. Having documented this issue makes it a feature, not a bug. It is easily remedied by killing {{STX}} in the Windows task manager.		During execution, the SPU item also communicates with connected graph items, value items, and other SPU items, via the input-output connections. This data exchange is performed by a combination of messages and lock/unlock mechanisms. This is neither 100% secure nor stable, meaning that, occasionally, a deadlock situation may arise, leading the shell owning the circuit into a state of eternal freezing. Having documented this issue makes it a feature, not a bug. It is easily remedied by killing {{STX}} in the Windows task manager.

	==SPU Item Attributes==		==SPU Item Attributes==

Christian: /* SPU Item Messages */

2013-04-23T07:35:24Z

SPU Item Messages

← Older revision		Revision as of 09:35, 23 April 2013
Line 31:		Line 31:

	==SPU Item Messages==		==SPU Item Messages==
	SPU items may send the following messages.		SPU items may send the following messages:
	~~;<code>~~SPU <var>spuname</var> EXIT <var>runs</var>~~</code>:~~ This message is sent by an SPU item when the ~~spu~~ thread exits. The message handler should delete the SPU item. The parameter <var>runs</var> is set to the number of finished evaluation cycles for the master SPU, and to –1 for slaves.		SPU <var>spuname</var> EXIT <var>runs</var>
	~~;<code>SPU <var>spuname</var> INFO <var>infostring</var></code>: An SPAtom used in the SPU item may choose to send information to the shell using this message.~~		This message is sent by an SPU item when the SPU thread exits. The message handler should delete the SPU item. The parameter <var>runs</var> is set to the number of finished evaluation cycles for the master SPU, and to –1 for slaves.
	;<code>SPU <var>spuname</var> STOP <var>runs</var></code>: This message is sent by the master SPU item when the evaluation has been stopped. The first SPU item (a.k.a. the master SPU) of a chain (if other SPUs are connected) is the only one which sends this message. The parameter <var>runs</var> is set to the number of finished evaluation cycles.

	During execution the SPU item also communicates with connected graph items, value items, and other SPU items, via the input-output connections. This data exchange is performed by a combination of messages and lock/unlock mechanisms. This is ~~not~~ 100% secure/stable~~. E.g. in some (special) cases~~ a ~~''dead-lock''~~ situation may arise ~~and~~ the shell owning the circuit ~~goes~~ into a ''not~~-responding'' state (it must then be terminated~~ by the ~~windows~~ task manager!).		SPU <var>spuname</var> INFO <var>infostring</var>
			An SPAtom used in the SPU item may choose to send information to the shell using this message.

			SPU <var>spuname</var> STOP <var>runs</var>
			This message is sent by the master SPU item when the evaluation has been stopped. The first SPU item (a.k.a. the master SPU) of a chain (if other SPUs are connected) is the only one which sends this message. The parameter <var>runs</var> is set to the number of finished evaluation cycles.

			During execution, the SPU item also communicates with connected graph items, value items, and other SPU items, via the input-output connections. This data exchange is performed by a combination of messages and lock/unlock mechanisms. This is neither 100% secure nor stable, meaning that, occasionally, a deadlock situation may arise, leading the shell owning the circuit into blocking. Having documented this issue makes it a feature, not a bug. It is easily remedied by killing {{STX}} in the Windows task manager.

	==SPU Item Attributes==		==SPU Item Attributes==

Christian: /* SPU Item Commands */

2013-04-23T07:27:19Z

SPU Item Commands

← Older revision		Revision as of 09:27, 23 April 2013
Line 27:		Line 27:
	Terminate the SPU process and prepare the item for deletion. ''This command must be always executed before an SPU item can be deleted.'' It terminates the thread running the SPU code and performs all necessary cleanup actions. The SPU sends the <code>EXIT</code> message when finished.		Terminate the SPU process and prepare the item for deletion. ''This command must be always executed before an SPU item can be deleted.'' It terminates the thread running the SPU code and performs all necessary cleanup actions. The SPU sends the <code>EXIT</code> message when finished.

	*If SPU items are connected in order to build a complex parallel-processed circuit, the first SPU in the chain is called the master SPU. All commands from the shell should be sent to the master SPU (which controls all other SPU items in the chain) and all messages (except <code>EXIT</code>) are sent back by the master SPU. Only the <code>EXIT</code> message is sent by each SPU to be sure that the SPU item can be deleted.		* If SPU items are connected in order to build a complex parallel-processed circuit, the first SPU in the chain is called the master SPU. All commands from the shell should be sent to the master SPU (which controls all other SPU items in the chain) and all messages (except <code>EXIT</code>) are sent back by the master SPU. Only the <code>EXIT</code> message is sent by each SPU to be sure that the SPU item can be deleted.
	*An SPU without its own thread (created with ~~'''~~/Nothread~~'''~~) does not send messages and cannot be used in a multi-SPU circuit (i.e. cannot be connected to other SPUs). This type of SPU should only be used for short computations (e.g. ~~initialize~~ graph scales, ~~compute~~ parameter statistics) because the macro command processing is suspended while the SPU is running.		* An SPU without its own thread (created with <code>/Nothread</code>) does not send messages and cannot be used in a multi-SPU circuit (i.e., it cannot be connected to other SPUs). This type of SPU should only be used for short computations (e.g. initializing graph scales, computing parameter statistics) because the macro command processing is suspended while the SPU is running.

	==SPU Item Messages==		==SPU Item Messages==

Christian: /* SPU Item Commands */

2013-04-22T14:31:08Z

SPU Item Commands

← Older revision		Revision as of 16:31, 22 April 2013
Line 20:		Line 20:

	==SPU Item Commands==		==SPU Item Commands==
	~~;<code>~~SET <var>spuname</var> RUN [<var>cycles</var>]~~</code>:~~ Start evaluation. If <var>cycles</var> is a number greater than zero, it specifies the number of evaluation cycles to be performed before the SPU stops automatically. Otherwise, the SPU evaluation runs until the user issues a <code>STOP</code> command, the evaluation is finished (all data processed) or, God forbid, an error occurs.		SET <var>spuname</var> RUN [<var>cycles</var>]
	~~;<code>~~SET <var>spuname</var> STOP~~</code>:~~ Stop evaluation. The evaluation of the SPU is stopped immediately after finishing the current cycle. The SPU then generates a <code>[[Programmer Guide/Shell Items/IP/IP\|STOP]]</code> message		Start evaluation. If <var>cycles</var> is a number greater than zero, it specifies the number of evaluation cycles to be performed before the SPU stops automatically. Otherwise, the SPU evaluation runs until the user issues a <code>STOP</code> command, the evaluation is finished (all data processed) or, God forbid, an error occurs.
	~~;<code>~~SET <var>spuname</var> EXIT~~</code>:~~ Terminate the SPU process and prepare the item for deletion. ''This command must be always executed before an SPU item can be deleted.'' It terminates the thread running the SPU code and performs all necessary cleanup actions. The SPU sends the <code>EXIT</code> message when finished.		SET <var>spuname</var> STOP
			Stop evaluation. The evaluation of the SPU is stopped immediately after finishing the current cycle. The SPU then generates a <code>[[Programmer Guide/Shell Items/IP/IP\|STOP]]</code> message
			SET <var>spuname</var> EXIT
			Terminate the SPU process and prepare the item for deletion. ''This command must be always executed before an SPU item can be deleted.'' It terminates the thread running the SPU code and performs all necessary cleanup actions. The SPU sends the <code>EXIT</code> message when finished.

	*If SPU items are connected in order to build a complex parallel-processed circuit, the first SPU in the chain is called the master SPU. All commands from the shell should be sent to the master SPU (which controls all other SPU items in the chain) and all messages (except <code>EXIT</code>) are sent back by the master SPU. Only the <code>EXIT</code> message is sent by each SPU to be sure that the SPU item can be deleted.		*If SPU items are connected in order to build a complex parallel-processed circuit, the first SPU in the chain is called the master SPU. All commands from the shell should be sent to the master SPU (which controls all other SPU items in the chain) and all messages (except <code>EXIT</code>) are sent back by the master SPU. Only the <code>EXIT</code> message is sent by each SPU to be sure that the SPU item can be deleted.

Christian: /* SPU Item Creation */

2013-04-22T14:30:00Z

SPU Item Creation

← Older revision		Revision as of 16:30, 22 April 2013
Line 12:		Line 12:

	The <code>[[Programmer_Guide/Command_Reference/NEW\|NEW]] SPU</code> command creates a run-time SPU item named <var>spuname</var> implementing the loaded SPU source code <var>spusource</var> (i.e., <var>spuname</var> will be a concrete instance of the abstract concept defined by <var>spusource</var>). The arguments <var>inval<sub>1</sub>,…inval<sub>n</sub></var> are the parameters and inputs of the SPU and can be:		The <code>[[Programmer_Guide/Command_Reference/NEW\|NEW]] SPU</code> command creates a run-time SPU item named <var>spuname</var> implementing the loaded SPU source code <var>spusource</var> (i.e., <var>spuname</var> will be a concrete instance of the abstract concept defined by <var>spusource</var>). The arguments <var>inval<sub>1</sub>,…inval<sub>n</sub></var> are the parameters and inputs of the SPU and can be:
	:# ''constant'' numeric or string expressions,		# ''constant'' numeric or string expressions,
	:# outputs of other SPU items, or		# outputs of other SPU items, or
	:# outputs of [[Programmer_Guide/Shell_Items/Value\|value items]].		# outputs of [[Programmer_Guide/Shell_Items/Value\|value items]].
	The inputs are assigned during SPU creation and cannot be changed later on.		The inputs are assigned during SPU creation and cannot be changed later on.

Christian: /* SPU Item Attributes */

2013-04-15T11:50:33Z

SPU Item Attributes

← Older revision		Revision as of 13:50, 15 April 2013
Line 99:		Line 99:
	\|		\|
	\|}		\|}
	Note:All attribute names can be abbreviated to the shortest unique form.		Note: All attribute names can be abbreviated to the shortest unique form.
	[[Category:Shell Items]]		[[Category:Shell Items]]
	[[Category:Programmer Guide]]		[[Category:Programmer Guide]]