Parameters

The parameters element describes the valid parameters that an operator can be configured with. It also describes the valid syntax for such parameter configurations.

Listing 11 gives the basic structure.

Listing 11: The parameters type

<xs:complexType name="parametersType">
  <xs:sequence>
    <xs:element name="allowAny" type="xs:boolean"/>
    <xs:element name="parameter" type="parameterType" minOccurs="0" maxOccurs="unbounded"/>
  </xs:sequence>
</xs:complexType>
          
<xs:complexType name="parameterType">
  <xs:sequence>
    <xs:element name="name" type="xs:string"/>
    <xs:element name="description" type="common:descriptionType" minOccurs="0" maxOccurs="1"/>
    <xs:element name="optional" type="xs:boolean"/>
    <xs:element name="rewriteAllowed" type="xs:boolean"/>
    <xs:element name="expressionMode" type="expressionModeType"/>
    <xs:element name="type" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="cardinality" type="xs:integer" minOccurs="0" maxOccurs="1"/>
    <xs:element name="portScope" type="portScopeType" minOccurs="0" maxOccurs="1"/>
    <xs:element name="customOutputFunction" type="xs:string" minOccurs="0" maxOccurs="1"/>
  </xs:sequence>
</xs:complexType>
            
<xs:complexType name="portScopeType">
  <xs:sequence>
    <xs:element name="port" type="xs:integer" maxOccurs="unbounded"/>
  </xs:sequence>
</xs:complexType>
              
<xs:simpleType name="expressionModeType">
  <xs:restriction base="xs:string">
    <xs:enumeration value="Attribute"/>
    <xs:enumeration value="AttributeFree"/>
    <xs:enumeration value="Constant"/>
    <xs:enumeration value="CustomLiteral"/>
    <xs:enumeration value="Expression"/>
    <xs:enumeration value="Nonexistent"/>
  </xs:restriction>
</xs:simpleType>     

The allowAny element is a Boolean flag that determines whether an operator can take arbitrary parameters, with no restrictions. An operator can accept arbitrary parameters. Yet still specify additional parameters, and associated restrictions.

Each parameter element contains several subelements. The name element is the name of the parameter as it appears in the SPL source code. For example, a Functor operator can have a filter parameter. The description element, which is optional, provides a description of the parameter. The optional element is a boolean that specifies whether the parameter is optional. A value of false implies that the parameter must be specified in the SPL source code.

An example use is as follows:

composite Main {                                                                     //1
  type TradeQuoteT = tuple<rstring ttype, rstring ticker, rstring dayAndTime>;       //2
  graph                                                                              //3
    stream<TradeQuoteT> TradeQuote = Beacon() {}                                     //4
    stream<TradeQuoteT> TradeFilter = Filter(TradeQuote) {                           //5
      param filter : ttype=="Trade" && ticker=="IBM";                                //6
    }                                                                                //7
}                                                                                    //8

A parameter can specify a rewriteAllowed element as true or false. If true, the compiler rewrites the expressions that appear in this parameter's values by substituting literals (including those values that result from compile-time evaluation step) with variables whose values are loaded at run time. This enables the compiler to generate less code for operators that differ slightly in their parameter configurations. In certain cases, the operator code generators might want to look into the parameter value to generate different code that is based on the particular value that is found or perform compile-time validation. For example, format: csv might result in generating specialized code for a source operator. In such cases, turn off expression rewrite.

The type of a parameter is either the SPL type of its values (such as list<ustring>) or a custom literal name (such as SourceFormat). For more information about SourceFormat, see the example in Context. The type can also be omitted, in which case any SPL type matches. The type subelement of a parameter can have an empty value, which has the same semantics as a missing type element.

The cardinality of a parameter is the maximum number of values it accepts. If omitted or the value is -1, the number of values is assumed to be unbounded. The number of parameter values must match the cardinality. The cardinality subelement can take a value of -1, which has the same semantics as a missing cardinality element.

The portScope element is used to limit the stream attributes that appear in a parameter value to a specific input port or to a list of input ports. Port indices start from 0. When omitted, there are no restrictions on stream attributes.

The optional customOutputFunction element of a parameter specifies the name of a custom output function set defined in the context element, and makes the functions that are defined in the set visible during the compilation of a parameter. It is the responsibility of the operator to generate correct C++ code that involves custom output functions with the parameter, in the same manner as it would be for a use in an output clause.

Listing 12 gives a sample XML segment for the parameters element from the Join operator.

Listing 12: Sample parameters XML segment

<parameters>
  <allowAny>false</allowAny>
  <parameter>
    <name>match</name>
    <optional>true</optional>
    <rewriteAllowed>true</rewriteAllowed>
    <expressionMode>Expression</expressionMode>
    <type>boolean</type>
    <cardinality>1</cardinality>
  </parameter>
  <parameter>
     <name>equalityLHS</name>
     <optional>true</optional>
     <rewriteAllowed>true</rewriteAllowed>
     <expressionMode>Expression</expressionMode>
     <portScope><port>0</port></portScope>
  </parameter>
  <parameter>
     <name>equalityRHS</name>
     <optional>true</optional>
     <rewriteAllowed>true</rewriteAllowed>
     <expressionMode>Expression</expressionMode>
     <portScope><port>1</port></portScope>
  </parameter>
</parameters>      

An example use in an SPL program is as follows:

Listing 13: Sample SPL use of parameters for Join operator

composite Main {
graph
  stream<rstring a, int32 eq1, int32 eq2> A = Beacon () {}
  stream<rstring b, int32 eq2, int32 field> B = Beacon () {}
  stream<int32 eq1, int32 field> J = Join (A; B) {
    window A : sliding, count(0);
           B : sliding, count(10);
    param match : A.a == B.b;
           equalityLHS: A.eq1, A.eq2;
           equalityRHS: B.eq2, B.field + 1;
  }
}