Programmer Guide/Shell Items/SPU: Difference between revisions

From STX Wiki
Jump to navigationJump to search
No edit summary
 
(44 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
A SPU is a shell item for controlling 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, which must be loaded before the SPU item (the runtime instance of the circuit) can be created.
{{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.


==SPU Item Creation==
==SPU Item Creation==
An SPU item is created using the <code>NEW SPU</code> command.
An SPU item is created using the <code>NEW SPU</code> command.
;<code>NEW SPU <var>spuname spusource inval1 ...</var> [/Nothread] [ /G ]</code>
NEW SPU <var>spuname</var> <var>spusource</var> <var>inval<sub>1</sub></var>&hellip; <var>inval<sub>n</sub></var> [/Nothread] [ /G ]
:;<var>spuname</var>:the name of the SPU item; the asterisk ('''*''') can be used to assign an automatically created unique name
;<var>spuname</var>: the name of the SPU item; if you supply an asterisk (&quot;<code>*</code>&quot;) instead of a name, {{STx}} will generate a unique name of its own.
:;<var>spusource</var>:the name of a loaded [[Programmer_Guide/Source_code#Definition_of_SPUs|SPU source code]]
;<var>spusource</var>: the name of a loaded [[Programmer_Guide/Source_code#Definition_of_SPUs|SPU source code]]
:;<var>inval1, ...</var>:the values for the SPU inputs; the values must be specified in the order defined in the SPU source header
;<var>inval<sub>1</sub></var>,&hellip; <var>inval<sub>n</sub></var>: the values for the SPU inputs; these values must be specified in the same order as they are defined in the SPU source header
:;/Nothread:do not create a SPU thread (SPU runs in the shell's thread);
;/Nothread: do run the SPU in a thread of its own (instead, the SPU will execute in the thread of the calling shell);
:;/G:create a [[Programmer_Guide/Shell_Items#Temporary_shell_items|temporary SPU item]]; use this option only together with '''/Nothread'''
;/G :create a [[Programmer_Guide/Shell_Items#Temporary_shell_items|temporary SPU item]]<br>'''N.B.:''' temporary SPU items ''must'' be run in the shell thread, meaning that you ''must'' combine the <code>/G</code> option with the <code>/Nothread</code> option.


The command creates a run-time SPU item named <var>spuname</var> which is based on the loaded SPU source code <var>spusource</var>. The arguments <var>inval1, ...</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>,&hellip;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! If the command is successful, the new SPU item is initialized and put into '''stop mode'''. The option /Nothread means that rather than creating an SPU-thread, the SPU runs in the shell's thread (this means the macro processing is blocked while the SPU is running).  
The inputs are assigned during SPU creation and cannot be changed later on.


If the <code>NEW SPU</code> command is successful, the new SPU item is initialized and will enter '''stop mode'''. The option <code>/Nothread</code> means that rather than creating an SPU thread, the SPU runs in the shell's own thread, meaning that script processing will be blocked while the SPU is running.


An SPU without its own thread does not send messages and cannot be used in a multi-SPU circuit (i.e. cannot be connected to other SPU's). 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.See [[Programmer Guide/Macro Library/FOREVER|SPU Item Commands]] for the <code>SET</code> commands and [[Programmer Guide/Shell Items/SPU/SPU Item Attributes|SPU Item Attributes]] for a list of attributes.
==SPU Item Commands==
SET <var>spuname</var> RUN [<var>cycles</var>]
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> 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.
* 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.


<splist
==SPU Item Messages==
parent=
SPU items may send the following messages:
sort=asc
SPU <var>spuname</var> EXIT <var>runs</var>
sortby=title
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.
showpath=no
 
liststyle=unordered
SPU <var>spuname</var> INFO <var>infostring</var>
kidsonly=yes
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 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==
{|class="einrahmen"
!attribute/argument !!description !!values
|-
|<code>!mode</code>
| current mode of the SPU item
|<code>RUN</code>, <code>STOP</code>, <code>EXIT</code>
|-
|<code>!nrun</code>
|number of finished evaluation cycles
|an integer &ge;0
|-
|<code>!maxrun</code>
|maximum number of ealuation cycles<BR>if equal 0, no maximum number is defined (''endless'' execution)
|an integer &ge;0
|-
|<code>!code</code>
|name of the SPU source code
|
|-
|<code>!noutput</code>
|number of SPU outputs
|an integer &ge;0
|-
|<code>!outputs</code>
|blank seperated list of all output names
|
|-
|<code>!output, <var>i</var></code>
|name of the output <var>i</var>, 0&le;<var>i</var>&lt;<code><var>spu</var>[!noutput]</code>
|
|-
|<code>!ninput</code>
|number of SPU inputs
|an integer &ge;0
|-
|<code>!inputs</code>
|blank seperated list of all output names
|
|-
|<code>!input, <var>i</var></code>
|name of the input <var>i</var>, 0&le;<var>i</var>&lt;<code><var>spu</var>[!ninput]</code>
|
|-
|<code>!thread</code>
|<code>1</code> if the SPU is executed in a own thread,<BR>0 if the SPU runs in the shell thread
|<code>0</code> or <code>1</code>
|-
|<code>!master</code>
|<code>1</code> if the SPU is the master and, otherwise <code>0</code> (slave)
|<code>0</code> or <code>1</code>
|-
|<code>!failed</code>
|<code>1</code> if the SPU execution has failed, otherwise <code>0</code>
|<code>0</code> or <code>1</code>
|-
|<code>!done</code>
|<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
|<code>0</code> or <code>1</code>
|-
|<code>!emsg</code> or <code>!lasterror</code>
|last SPU error message (for debugging)<BR>This attribute is empty if no SPAtom had an error to report.
|
|}
Note: All attribute names can be abbreviated to the shortest unique form.

Latest revision as of 11:38, 23 October 2015

SPU Item
NEW SET ATTRIBUTES MESSAGES

An SPU (signal processing unit) is a shell item for controlling (software) signal processing units (SPUs). An SPU is a circuit connecting one or more Signal Processing Atom together. The ciruit (its SP atoms, inputs, outputs, and internal connections) is defined in a 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.

SPU Item Creation

An SPU item is created using the NEW SPU command.

NEW SPU spuname spusource inval1invaln [/Nothread] [ /G ]
spuname
the name of the SPU item; if you supply an asterisk ("*") instead of a name, STx will generate a unique name of its own.
spusource
the name of a loaded SPU source code
inval1,… invaln
the values for the SPU inputs; these values must be specified in the same order as they are defined in the SPU source header
/Nothread
do run the SPU in a thread of its own (instead, the SPU will execute in the thread of the calling shell);
/G
create a temporary SPU item
N.B.: temporary SPU items must be run in the shell thread, meaning that you must combine the /G option with the /Nothread option.

The NEW SPU command creates a run-time SPU item named spuname implementing the loaded SPU source code spusource (i.e., spuname will be a concrete instance of the abstract concept defined by spusource). The arguments inval1,…invaln are the parameters and inputs of the SPU and can be:

  1. constant numeric or string expressions,
  2. outputs of other SPU items, or
  3. outputs of value items.

The inputs are assigned during SPU creation and cannot be changed later on.

If the NEW SPU command is successful, the new SPU item is initialized and will enter stop mode. The option /Nothread means that rather than creating an SPU thread, the SPU runs in the shell's own thread, meaning that script processing will be blocked while the SPU is running.

SPU Item Commands

SET spuname RUN [cycles]

Start evaluation. If cycles 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 STOP command, the evaluation is finished (all data processed) or, God forbid, an error occurs.

SET spuname STOP

Stop evaluation. The evaluation of the SPU is stopped immediately after finishing the current cycle. The SPU then generates a STOP message

SET spuname 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 EXIT 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 EXIT) are sent back by the master SPU. Only the EXIT 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., 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 items may send the following messages:

SPU spuname EXIT runs

This message is sent by an SPU item when the SPU thread exits. The message handler should delete the SPU item. The parameter runs is set to the number of finished evaluation cycles for the master SPU, and to –1 for slaves.

SPU spuname INFO infostring

An SPAtom used in the SPU item may choose to send information to the shell using this message.

SPU spuname STOP runs

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

attribute/argument description values
!mode current mode of the SPU item RUN, STOP, EXIT
!nrun number of finished evaluation cycles an integer ≥0
!maxrun maximum number of ealuation cycles
if equal 0, no maximum number is defined (endless execution)
an integer ≥0
!code name of the SPU source code
!noutput number of SPU outputs an integer ≥0
!outputs blank seperated list of all output names
!output, i name of the output i, 0≤i<spu[!noutput]
!ninput number of SPU inputs an integer ≥0
!inputs blank seperated list of all output names
!input, i name of the input i, 0≤i<spu[!ninput]
!thread 1 if the SPU is executed in a own thread,
0 if the SPU runs in the shell thread
0 or 1
!master 1 if the SPU is the master and, otherwise 0 (slave) 0 or 1
!failed 1 if the SPU execution has failed, otherwise 0 0 or 1
!done 1 if the SPU execution is finished, otherwise 0
This flag can be used to determine if the execution can be continued (e.g. after a STOP or a single step) or not
0 or 1
!emsg or !lasterror last SPU error message (for debugging)
This attribute is empty if no SPAtom had an error to report.

Note: All attribute names can be abbreviated to the shortest unique form.

Navigation menu

Personal tools