Class that provides code generation helper utilities. More...

List of all members.

Detailed Description

Class that provides code generation helper utilities.

Member Function Documentation

Given an operator instance model, produces the prolog code for the operator's header code generator template

Parameters:

Given an operator instance model, produces the epilog code for the operator's header code generator template

Parameters:

Given an operator instnce model, produces the prolog code for the operator's implementation code generator template

Parameters:

Given an operator instance model, produces the epilog code for the operator's implementation code generator template

Parameters:

Given an output port object, return true if any output assignment expression has side effects, otherwise false. This can be used to pull output tuple initialization out of a loop.

Parameters:
Returns:
1 if any output assignment has side effects, 0 otherwise

Example: For

  • tuple type tuple<int8 a, int8 b>, and
  • SPL output assignment fragment output S : a = x, b = y; this function will return 0.

For

  • SPL output assignment fragment output S : a = x++, b = statefulFunction(y); this function will return 1.

Given an output port object, return true if any output assignment expression contains an input attribute within the expression. This can be used to pull output tuple initialization out of a loop

Parameters:
Returns:
1 if any output assignment contains an input attribute, 0 otherwise

Example: For

  • tuple type tuple<int8 a, int8 b>, and
  • SPL output assignment fragment output S : a = x, b = y; this function will return 1 if x or y are input stream attributes, 0 if they are both state variables.

Given an output port object, return the C++ expression which can be used to initialize a tuple for the port with the output assignments.

Parameters:
Returns:
a string containing the expression to be used for initializing the output tuple

Example: For

  • tuple type tuple<int8 a, int8 b>, and
  • SPL output assignment fragment output S : a = x, b = y;

this function will produce the following:

  • $iport0.get_x(), $iport0.get_y()

This can be used as:

my $assignments = SPL::CodeGen::getOutputTupleCppInitializer($outputPort);
emitALine "OPort${index}Type otuple($assignments);";

If an output assignment uses a Custom Output Function, the result will contain a call to a function of the same name. If this is not desired, the operator should walk the assignments one at a time, examining each one to generate the desired code.

Given a tuple name and an output port object, return a C++ code segment which can be used to assign an already initialized tuple for the port with the output attribute assignments captured in the output port object.

Parameters:
Returns:
a string containing the statements to carry out the output assignments

Example: For

  • tuple type tuple<int8 a, int8 b>, and
  • SPL output assignment fragment output S : a = x, b = y;

getOutputTupleCppAssignments('fred', $port) will produce the following:

  • fred.set_a($iport0.get_x()); fred.set_b($iport0.get_y());

Given a tuple name and an output port object, return a C++ code segment which can be used to assign an already initialized tuple for the port with the output attribute assignments captured in the output port object. This is the same as getOutputTupleCppAssignments except for the additional sideEffects parameter which is used to specify whether we want assignments which contain side effects on the RHS (or not).

Parameters:
Returns:
a string containing the statements to carry out the output assignments

Example: For

  • tuple type tuple<int8 a, int8 b>, and
  • SPL output assignment fragment output S : a = x, b = y++;
  • we only want assignment fragements which contain side effects

getOutputTupleCppAssignments('fred', $port, 1) will produce the following:

  • fred.set_b($iport0.get_y());

Given a parameter object, return a list of C++ types corresponding to the expressions contained within the parameter. The resulting list can be used as the types parameter in an emitClass call.

Parameters:
Returns:
list of types

Given a parameter object, return a C++ expresion that can be used as the constructor initializer for an object of type returned by an emitClass call.

Parameters:
Returns:
string to be used as a constructor initializer or undef if param is not defined

Example: For

  • SPL parameter assignment fragment param key: a, sqrt(b);

this function will produce the following:

  • $iport0.get_a(),SPL:Functions::Math::sqrt($iport0.get_b())

Obtain the C++ expression adapted for the given tuple context, where the references to input tuples are replaced with the names given by the tuples parameter.

Parameters:
Returns:
a string with the adapted C++ expression

Example: Consider a Filter operator with a filter parameter that defines a predicate over the input tuple attributes. Here is how one can use the filter expression from within the code generator template:

<%
my $filterParam = $model->getParameterByName("filter");
my $filterExpr = $filterParam->getValueAt(0)->getCppExpression();
%>
void MY_OPERATOR::process(Tuple & tuple, uint32_t port) {
if (<%=SPL::CodeGen:adaptCppExpression($filterExpr, "tuple")%>) {
...
}
}

Obtain the C++ expression with all references to lit$[0-9]*, state$ and iport$[0-9]+History prefixed by the prefix parameter.

Parameters:
Returns:
a string with the prefixed C++ expression

Example: Consider operator with a helper class that needs to handle general C++ expressions. The helper class will need to ensure that literals and state variable s(which are in the base operator class) can be compiled in C++. If the helper class has a reference to the operator class in variable _oper, then we can prefix "_oper." to all literals, and the C++ expression will be valid. a predicate over the input tuple attributes. Here is how one can use the C++ expression from a Helper class:

<%
my $param = $model->getParameterByName("param");
my $expr = $param->getValueAt(0)->getCppExpression();
%>
class HelperClass {
MY_OPERATOR_SCOPE::MY_OPERATOR& _oper;
public:
HelperClass(MY_OPERATOR_SCOPE::MY_OPERATOR& oper) : _oper(oper) {}
void doSomething() {
int value = <%=SPL::CodeGen::prefixLiteralsAndStatesInCppExpressions($expr, "_oper.")%>;
}
}

Obtain the Perl value from a C++ expression of a given SPL type.

Precondition:
the C++ expression must contain a C++ literal
the type must belong to one of the following categories: integral, float, decimal, string, boolean
Parameters:
Returns:
a Perl value, or undef if unsuccessful

Example: Consider a Filter operator with a filter parameter that defines a predicate over the input tuple attributes. Here is how one can use the filter expression from within the code generator template:

# Assume that the 'count' parameter is a Constant expression and expression
# rewrite is turned off for the parameter.
<%
my $count = $model->getParameterByName("count")->getValueAt(0);
my $c = SPL::CodeGen::extractPerlValue($count->getCppExpression(), $count->getSPLType());
if($c>4) { ... }
%>

Generate code to submit a tuple to a given output port. If the output attribute assignments indicate that the tuple is simply forwarded from the given input port, then the generated code will not create a separate tuple and will just forward the input one, as long as the port mutability settings allow it.

Parameters:

Example: emitSubmitOutputTuple($iport, $oport) will produce the following code submit($iport0, 0); if the output port index is 0, the output assignments indicate a simple forwarding, and the port mutability settings allow submitting the input tuple directly to the output port. Otherwise, it will generate code like: OPort0Type otuple($iport0.get_x()+5); submit(otuple, 0);.

Generate code to submit a cached tuple to a given output port. If the output attribute assignments indicate that the tuple is simply forwarded from the given input port, then the generated code will not populate the cached tuple and will just forward the input one, as long as the port mutability settings allow it.

Parameters:

Example: emitSubmitCachedOutputTuple('fred', $iport, $oport) will produce the following code submit($iport0, 0); if the output port index is 0, the output assignments indicate a simple forwarding, and the port mutability settings allow submitting the input tuple directly to the output port. Otherwise, it will generate code like: fred.set_x($iport0.get_x()+5); submit(fred, 0);.

Given a name and a list of types, generates a C++ class that is hashable and contains member fields with the specified types. The class will have public members with the names 'field<index>_', one for each element in the $types list. The class will also have empty, copy, and member initializer constructors, assignment operator, as well as equality and non-equality comparison operators.

Parameters:
Returns:
the name of the class, which is different than the parameter name. NOTE: emitClass() call should come before the headerPrologue() call.

Example usage from within a code generator template:

// This is an <opname>_h.cgt file
<%
my $keyParam = $model->getParameterByName("key");
my @keyTypes = SPL::CodeGen::getParameterCppTypes($keyParam);
my $keyClass = SPL::CodeGen::emitClass($model, "MyKey", @keyTypes);
...
SPL::CodeGen::headerPrologue($model);
%>

Given a window object from the operator instance model, returns the C++ type for the window.

Parameters:

Example 1: For a partitioned sliding window with a count-based eviction policy and a delta-based trigger policy,

  • getWindowCppType($window, "MyTupleT", "MyPartitionT")

will produce the following:

  • SPL::SlidingWindow<MyTupleT, MyPartitionT>

Example 2: For an un-partitioned tumbling window with a count-based eviction and a count-based trigger policy,

  • getWindowCppType($window, "MyTupleT")

will produce the following:

  • SPL::TumblingWindow<MyTupleT>

Example 3: For an un-partitioned sliding window with a count-based eviction and a count-based trigger policy and incremental checkpointing,

  • getWindowCppType($window, "MyTupleT", '', 'SPL::IncrDeque', 'SPL::IncrUnorderedMap')

will produce the following:

  • SPL::SlidingWindow<MyTupleT, int32_t, SPL::IncrDeque<MyTupleT>, SPL::IncrUnorderedMap<int32_t, SPL::IncrDeque<MyTupleT> > >

Given a window object from the operator instance model, returns the C++ type initializer for the window.

Parameters:
Note:
This routine will NOT handle partition eviction policies

Example: For a sliding window with a count-based eviction policy of size 10 and a delta-based trigger policy on an int32 attribute with a delta of 15, the call

  • getWindowCppInitializer($window, "MyTupleT", "", "get_age")

will produce the following:

  • *this, 0, SPL::CountWindowPolicy(10), SPL::DeltaWindowPolicy<MyTupleT,uint32,&MyTupleT::get_age>(15)

Given a window object for a partitioned window from the operator instance model, returns the C++ type initializer for the window.

Parameters:

Example: For a sliding window with a count-based eviction policy of size 10 and a delta-based trigger policy on an int32 attribute with a delta of 15, and partitioned(tupleCount(100)), the call

  • getPartitionedWindowCppInitializer($window, "MyTupleT", "LRU", "", "get_age")

will produce the following:

  • *this, 0, SPL::CountWindowPolicy(10), SPL::DeltaWindowPolicy<MyTupleT,uint32,&MyTupleT::get_age>(15), ::SPL::TupleCountPartitionEvictionPolicy(100, ::SPL::PartitionEvictionPolicy::LRU)

Given a window object from the operator instance model and a window policy, returns the code that creates a C++ object for the policy

Parameters:

Example 1: For a sliding window with a count-based eviction policy of size 10, the call

  • getWindowPolicyCppObject($window, 1, "MyTupleT")

will produce the following:

  • SPL::CountWindowPolicy(10)

Example 2: For a sliding window with a delta-based trigger policy on an int32 attribute with a delta of 15, the call

  • getWindowPolicyCppObject($window, 0, "MyTupleT", "get_age")

will produce the following:

  • SPL::DeltaWindowPolicy<MyTupleT,uint32,&MyTupleT::get_age>(15)

Example 3: For a sliding window with a delta-based trigger policy on an int32 attribute with a delta of 15, where the window stores pointers, the call

  • getWindowPolicyCppObject($window, 0, "MyTupleT*", "get_age")

will produce the following:

  • SPL::DeltaWindowPolicy<MyTupleT*,uint32,&MyTupleT::get_age>(15)

Given a window object from the operator instance model, returns the C++ initializer that can be appended to the window initializer to set the partition evicition policy. If there is no partition eviction policy, return an empty string

Parameters:

Example: For a partition eviction policy of partitionAge(value), return

  • , ::SPL::PartitionEvictionPolicy::PartitionAge(value)

Given a window object from the operator instance model, returns the C++ type for the WindowEvent class that is used to handle events from the window.

Parameters:

Example 1: For a partitioned sliding window with a count-based eviction policy and a delta-based trigger policy,

  • getWindowEventCppType($window, "MyTupleT", "MyPartitionT")

will produce the following:

  • SPL::WindowEvent<MyTupleT, MyPartitionT>

Example 2: For an un-partitioned sliding window with a count-based eviction and a count-based trigger policy,

  • getWindowEventCppType($window, "MyTupleT")

will produce the following:

  • SPL::WindowEvent<MyTupleT>

Example 3: For an un-partitioned sliding window with a count-based eviction and a count-based trigger policy and incremental checkpointing,

  • getWindowEventCppType($window, "MyTupleT", '', 'SPL::IncrDeque', 'SPL::IncrUnorderedMap')

will produce the following:

  • SPL::WindowEvent<MyTupleT, int32_t, SPL::IncrDeque<MyTupleT>, SPL::IncrUnorderedMap<int32_t, SPL::IncrDeque<MyTupleT> > >

Given a list of window configurations, verify that the configurations are valid and return a reference to a list of configurations that can be used as input to validateWindowConfiguration and checkWindowConfiguration functions. The input list contains one hash reference for each configuration. A hash that represents a window configuration contains one or more of the following mappings:

  • type => <window-type>, where the window type is one of $SPL::Operator::Instance::Window::TUMBLING and SLIDING.
  • eviction => <eviction-policy>, where the eviction policy is one of $SPL::Operator::Instance::Window::COUNT, DELTA, TIME, and PUNCT.
  • trigger => <trigger-policy>, where the trigger policy is one of $SPL::Operator::Instance::Window::COUNT, DELTA, and TIME.
  • partitioned => <partition-status>, where the partition status is 0 or 1. These mappings are treated as conjunctions.
    Parameters:
    Returns:
    a reference to the list of configurations
    Here is an example use from the Sort operator, which creates two configurations, one that accepts any tumbling window, another one that accepts sliding windows with count based trigger and eviction policies:
    my $confs = SPL::CodeGen::createWindowConfigurations(
    { type => $SPL::Operator::Instance::Window::TUMBLING },
    { type => $SPL::Operator::Instance::Window::SLIDING,
    eviction => $SPL::Operator::Instance::Window::COUNT,
    trigger => $SPL::Operator::Instance::Window::COUNT});

Given an input port and a list of window configurations (created via createWindowConfigurations), verifies that the input port has a valid window configuration. Prints an error message and exits if the window configuration of the input port is not among the provided configurations.

Parameters:

Example use from the Sort operator:

my $confs = SPL::CodeGen::createWindowConfigurations(
{ type => $SPL::Operator::Instance::Window::TUMBLING },
{ type => $SPL::Operator::Instance::Window::SLIDING,
eviction => $SPL::Operator::Instance::Window::COUNT,
trigger => $SPL::Operator::Instance::Window::COUNT});
my $iport = $model->getInputPortAt(0);
SPL::CodeGen::validateWindowConfiguration($iport, $confs);

Given an input port and a list of window configurations (created via createWindowConfigurations), checks if the input port has a valid window configuration. Returns 0 if the window configuration of the input port is not among the provided configurations, and 1 otherwise.

Parameters:
Returns:
1 if the configuration is valid, 0 otherwise

Example use from the Sort operator:

my $confs = SPL::CodeGen::createWindowConfigurations(
{ type => $SPL::Operator::Instance::Window::TUMBLING },
{ type => $SPL::Operator::Instance::Window::SLIDING,
eviction => $SPL::Operator::Instance::Window::COUNT,
trigger => $SPL::Operator::Instance::Window::COUNT});
my $iport = $model->getInputPortAt(0);
my $res = SPL::CodeGen::checkWindowConfiguration($iport, $confs);

Check if the output tuple to be created is an exact copy of the input tuple

Parameters:
Returns:
1 if the input tuple is used directly to generate the output tuple

Given an input or output port, and a list of schema restrictions, ensure that the tuple that the port is consuming/producing contains all of the desired schema name/types. If there are attributes/types missing from the tuple, generate an error. For each restriction, there must be at least one attribute that satisfies it.

Parameters:

schema is a list of hash references that represent schema restrictions using one or more of the following mappings:

  • name => "attributeName"
  • type => "splType" or type => [ "splType", "splType" ... ]

NOTE: The only blanks allowed in the SPL type string are those that separate a tuple attribute type from the name ("int32 attr"). All types are 'unwound' to the expanded SPL type. User defined type names are not allowed.

Here is an example use, which is looking for an attribute foo with type rstring or int32, any attribute with type tuple<int32 x, rstring y>, and an attribute bar with any type.

SPL::CodeGen::checkMinimalSchema ($model->getInputPortAt(0),
{ name => "foo", type => ["rstring", "int32] },
{ type => "tuple<int32 x,rstring y>" },
{ name => "bar" });

Given an input or output port, and a list of schema restrictions, ensure that the tuple that the port is consuming/producing only contains attributes with the desired schema name/types. If there are attributes or types in the schema that are not supported, generate an error. For each attribute, there must be at least one restriction that permits it.

Parameters:

schema is a list of hash references that represent schema restrictions using one or more of the following mappings:

  • name => "attributeName"
  • type => "splType" or type => [ "splType", "splType" ... ]

NOTE: The only blanks allowed in the SPL type string are those that separate a tuple attribute type from the name ("int32 attr"). All types are 'unwound' to the expanded SPL type. User defined type names are not allowed.

Here is an example use: If attribute foo is present, it must have type rstring or ustring, any attribute with type tuple<int32 x, rstring y> is acceptable, and an attribute with name bar' is allowed.

SPL::CodeGen::checkMaximalSchema ($model->getInputPortAt(0),
{ name => "foo", type => [ "rstring", "ustring" ] },
{ type => "tuple<int32 x,rstring y>" },
{ name => "bar" });

Given an input or output port, and a list of schema restrictions, ensure that the tuple that the port is consuming/producing contains attributes of the right names/types. If an attribute in the tuple is in the list of restrictions, it must have the right type. Any attributes NOT in the schema restrictions are accepted without errors. For each attribute, there must be at least one restriction with a matching name that is satisfied.

Parameters:

schema is a list of hash references that represent schema restrictions using one or more of the following mappings:

  • name => "attributeName"
  • type => "splType" or type => [ "splType", "splType" ... ]

NOTE: The only blanks allowed in the SPL type string are those that separate a tuple attribute type from the name ("int32 attr"). All types are 'unwound' to the expanded SPL type. User defined type names are not allowed.

Here is an example use: If an attribute foo is present, it must have type rstring or int32,

SPL::CodeGen::checkAnySchema ($model->getInputPortAt(0),
{ name => "foo", type => [ "rstring", "int32" ]});

This function allows printing to the console during code generation. During code generation STDOUT is redirected. Attempts to print to it will result in corruption of the code generator. Note that if no optional params are passed the Perl print function will be called.

Parameters:

This function is similar to the print() method with the addition of a new line added at the end.

Parameters:

This function is similar to the print() method except that it only prints if the -v or –verbose-mode compiler option has been specified.

Parameters:

This function is similar to the println() method except that it only prints if the -v or –verbose-mode compiler option has been specified.

Parameters:

Prints 'WARNING' plus the contents of the format string.

Parameters:

This function is the same as warn() with the addition of a newline at the end.

Parameters:

This function is the same as warn() except that it only prints if the -v or –verbose-mode compiler option has been specified.

Parameters:

This function is the same as warnVerbose() with the addition of a new line at the end.

Parameters:

Prints 'ERROR ' plus the format string to STDERR.

Parameters:

This function is the same as error() with the addition of a newline at the end.

Parameters:

This function enables the printing of the format string to STDERR prior to exiting.

Parameters:

This method provides the same functionality as exitln with the addition of a new line at the end.

Parameters:

This method takes a compile-time path and converts it to a runtime path. If the compile-time path points into a toolkit, then that path will reflect the runtime location of that toolkit, otherwise the original path will be used.

Parameters:

This method takes a paramenter value representing a run-time path and converts it to an expression that can be used at compile time to access resources. undef is returned if the parameter value cannot be evaluated. The operator model must specify <splExpressionTree param="true"> for this to be used.

Parameters: