SPU

From STX Wiki
Jump to navigationJump to search

An SPU 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 inval1 ... [/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, ...
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 which is based on the loaded SPU source code spusource. The arguments inval1,… 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!

If the NEW SPU 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, 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 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 item for deletion. This function must be 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. 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.

SPU Item Messages

SPU items can 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, value 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 Item Attributes

attribute description values
!mode current mode of the SPU item RUN, STOP, EXIT
!nrun number of finished evaluation cycles ≥0
!maxrun maximum number of ealuation cycles
if equal 0, no maximum number is defined (endless execution)
≥0
!code name of the SPU source code
!noutput number of SPU outputs ≥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 ≥0
!inputs blank seperated list of all output names
!input,i name of the output i
0≤i<spu[!ninput]
!thread 1 if the SPU is executed in a own thread
0 if the SPU runs in the shell's 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)
the attribute is empty if no error was reported by a SP-atom

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

Navigation menu

Personal tools