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 inval1… invaln [/Nothread] [ /G ]
- the name of the SPU item; if you supply an asterisk ("
*") instead of a name, STx will generate a unique name of its own.
- 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
- do run the SPU in a thread of its own (instead, the SPU will execute in the thread of the calling shell);
- create a temporary SPU item
N.B.: temporary SPU items must be run in the shell thread, meaning that you must combine the
/Goption with 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:
- constant numeric or string expressions,
- outputs of other SPU items, or
- outputs of value items.
The inputs are assigned during SPU creation and cannot be changed later on.
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
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
EXITmessage 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
||current mode of the SPU item|
||number of finished evaluation cycles||an integer ≥0|
||maximum number of ealuation cycles
if equal 0, no maximum number is defined (endless execution)
|an integer ≥0|
||name of the SPU source code|
||number of SPU outputs||an integer ≥0|
||blank seperated list of all output names|
||name of the output i, 0≤i<
||number of SPU inputs||an integer ≥0|
||blank seperated list of all output names|
||name of the input i, 0≤i<
0 if the SPU runs in the shell thread
This flag can be used to determine if the execution can be continued (e.g. after a
||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.