Programmer Guide/Shell Items/SPU

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 inval1… invaln [/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

inval₁,… inval_n

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 inval₁,…inval_n 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.