Programmer Guide/Shell Items/SPU

A SPU is a shell item for controlling 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, which must be loaded before the SPU item (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; the asterisk (*) can be used to assign an automatically created unique name

spusource

the name of a loaded SPU source code

inval1, ...

the values for the SPU inputs; the values must be specified in the order defined in the SPU source header

/Nothread

do not create a SPU thread (SPU runs in the shell's thread);

/G

create a temporary SPU item; use this option only together with /Nothread

The 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 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).

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.

Notes:

• 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, !lasterror	last SPU error message (for debugging)

<splist parent= sort=asc sortby=title showpath=no liststyle=unordered kidsonly=yes >