Use of Messages in Primitives

Here are a couple of simple examples of primitives that produce and consume messages.

For more advanced samples, look in the MLDesigner distribution for primitives that produce or consume messages. The image processing classes and primitives, which are briefly described in Image Particles provide a particularly rich set of examples. The matrix classes described in Matrix Data Types are also good examples. The matrix classes are recognized in the MLDesigner kernel.

defprimitive
{
name { PackInt }
domain { SDF }
desc
{
Accept integer inputs and produce IntVecData messages.
}

input
{
name { Input }
type {int}
}

output
{
name { Output }
type { message }
}

defparameter
{
name { length }
type {int}
default {"10"}
desc {"number of values per message"}
}

ccinclude {"kernel/Message.h", "IntVecData.h"}

setup
{
Input.setSDFParams(int(length),int(length-1));
}

go
{
int tLength = length;
IntVecData* pd = new IntVecData(tLength);

// Fill in message. Input%0 is newest, must reverse
for(int i = 0; i < tLength; ++i)
pd->mData[tLength-i-1] = int(Input%i);

Envelope pkt(*pd);
Output%0 << pkt;
}
}

Since this is an SDF primitive, it must produce and consume a constant number of tokens on each step, so the message length must be fixed (though it is controllable with a parameter). See Setting SDF Porthole Parameters for an explanation of the setSDFParams method. Notice that the Output porthole is declared to be of type message. Notice also the ccinclude statement, the programmer has to include the file Message.h in all message-manipulating primitives, and he also has to include the definition of the specific message type he wishes to use. The code itself is fairly straightforward. An IntVecData object is created with the new command, it is filled in with data, put into an Envelope and is sent. Resist the temptation to declare the IntVecData object as a local variable: it will not work. It must reside on the heap. Here is a primitive to do the inverse operation:

defprimitive
{
name { UnPackInt }
domain { SDF }
desc
{
Accept IntVecData messages and produce integers.
The first "length" values from each message are produced.
}

input
{
name { Input }
type { message }
}

output
{
name { Output }
type {int}
}

defparameter
{
name { length }
type {int}
default {"10"}
desc {"number of values output per message"}
}

ccinclude {"kernel/Message.h", "IntVecData.h"}

setup
{
Output.setSDFParams(int(length),int(length-1));
}

go
{
Envelope pkt;
(Input%0).getMessage(pkt);

if(!pkt.typeCheck("IntVecData"))
{
Error::abortRun(*this,pkt.typeError("IntVecData"));
return;
}

const IntVecData* pd = (const IntVecData*)pkt.myData();
if(pd->length() < int(length))
{
Error::abortRun(*this,
"Received message is too short");
return;
}

for(int i = 0; i < int(length); ++i)
Output%(int(length)-i-1) << pd->mData[i];
}
}

Because the domain is SDF, we must always produce the same number of outputs regardless of the size of the messages. The simple approach taken here is to require at least a certain amount of data or else to trigger an error and abort the execution.

The operations here are to declare an Envelope object pkt, get the data from the particle into pkt variable by calling the getMessage method, check the type, and then access the contents. Notice the cast operation, this is needed because myData returns a const pointer to class Message. It is important that the programmer converts the pointer to const IntVecData* and not IntVecData* because we have no right to modify the message through this pointer. Many C++ compilers will not warn by default about ”casting away const”. We recommend turning on compiler warnings when compiling code that uses messages to avoid getting into trouble (for g++, say -Wcast-qual). If the programmer wishes to modify the message and then send the result as an output, he would call writableCopy instead of myData, modify the object, then send it on its way as seen in the previous primitive.