Input ports

The inputPorts element describes the input configurations of an operator.

Listing 14: The input ports type

Listing 14 gives the basic structure.

<xs:complexType name="inputPortsType">
  <xs:sequence>
     <xs:element name="inputPortSet" type="inputPortSetType" minOccurs="0" maxOccurs="unbounded"/>
     <xs:element name="inputPortOpenSet" type="inputPortOpenSetType" minOccurs="0" maxOccurs="1"/>
  </xs:sequence>
</xs:complexType>
          
<xs:complexType name="inputPortOpenSetType">
  <xs:sequence>
     <xs:element name="description" type="common:descriptionType" minOccurs="0" maxOccurs="1"/>
     <xs:element name="windowingDescription" type="common:descriptionType" minOccurs="0" maxOccurs="1"/>
     <xs:element name="tupleMutationAllowed" type="xs:boolean"/>
     <xs:element name="windowingMode" type="windowingModeType"/>
     <xs:element name="windowPunctuationInputMode" type="inputPunctuationModeType"/>
     <xs:element name="controlPort" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
     <xs:element name="windowExpressionMode" type="windowExpressionModeType" 
minOccurs="0" maxOccurs="1"/>
     <xs:element name="rewriteAllowedForWindowExpression" type="xs:boolean" minOccurs="0" 
maxOccurs="1"/>
  </xs:sequence>
</xs:complexType>
          
<xs:complexType name="inputPortSetType">
  <xs:complexContent>
     <xs:extension base="inputPortOpenSetType">
        <xs:sequence>
           <xs:element name="cardinality" type="xs:integer"/>
           <xs:element name="optional" type="xs:boolean"/>
        </xs:sequence>
     </xs:extension>
  </xs:complexContent>
</xs:complexType>
            
<xs:simpleType name="windowingModeType">
  <xs:restriction base="xs:string">
     <xs:enumeration value="NonWindowed"/>
     <xs:enumeration value="Windowed"/>
     <xs:enumeration value="OptionallyWindowed"/>
  </xs:restriction>
</xs:simpleType>
                
<xs:simpleType name="windowExpressionModeType">
  <xs:restriction base="xs:string">
     <xs:enumeration value="Constant"/>
     <xs:enumeration value="AttributeFree"/>
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="inputPunctuationModeType">
  <xs:restriction base="xs:string">
     <xs:enumeration value="Expecting"/>
     <xs:enumeration value="Oblivious"/>
     <xs:enumeration value="WindowBound"/>
  </xs:restriction>
</xs:simpleType>

Input ports are defined in terms of port sets. A port set is a fixed number of ports that share a configuration, which avoids repetition of the same configuration for different ports. A port set can be open, in which case it can contain zero or more ports with the same configuration. An inputPorts element contains zero or more inputPortSet elements, followed by an optional inputPortOpenSet element.

The structure of an input port open set, as the input port set extends from the open variant, has several elements. The tupleMutationAllowed element defines whether the processing logic attached to the input port (including both the logic that is associated with the operator's process functions and the processing that is done as part of the onTuple clauses that are specified in the SPL code) can mutate an incoming tuple. It can be set to true for operators that want to modify the tuples they receive. The windowingMode element specifies the valid windowing configurations for the port. Options include NonWindowed, Windowed, and OptionallyWindowed. The windowPunctuationInputMode element specifies the punctuation semantics of the input port. The valid options are:
  • Expecting - This port expects window punctuation in order for the operator to function correctly and thus must be fed a punctuated stream.
  • Oblivious - This port does not require punctuation in order for the operator to work correctly and thus has no restrictions on the connections that can be attached to it.
  • WindowBound - This port is an Expecting port if it has a punctuation-based window, and an Oblivious port otherwise.

The optional controlPort element tells the compiler that tuples received on this port are used only to control the operator, and no tuples are submitted when tuples are processed on this port. If not specified, the value is false. The SPL compiler emits warnings when loops are found in the operator graph, as this situation can lead to deadlock or infinite recursion. Setting controlPort to true tells the compiler that this port does not submit further tuples, and that is an expected (and harmless) feedback loop, so no warning is emitted for this port.

The optional windowExpressionMode element tells the compiler if the expressions in count, time, and delta must be constants that can be evaluated at compile time, or if runtime expressions that do not reference input tuple attributes are valid. If not specified, the default is Constant. If the windowExpressionMode element is set to AttributeFree, an expression such as time ((int32) getSubmissionTimeValue("timeParam")) can be used. For delta, only the second argument is allowed to be a runtime attribute-free expression. The first argument is still an attribute from the input stream.

The optional rewriteAllowedForWindowExpression element, if set to true, tells the compiler that it can rewrite the window expression the same way the rewriteAllowed element rewrites the expressions that appear in the parameter values. For more information about the rewriteAllowed element, see Parameters. If the rewriteAllowedForWindowExpression element is not specified, by default the value is set to false. rewriteAllowedForWindowExpression must be false (or omitted) if the C++ primitive operator wants to examine the value as a literal.

An input port set contains two additional elements on top of what is included in an input port open set. The cardinality element defines the number of ports that the port set represents. The optional element specifies whether the port set is optional. Even though not dictated by the XML schema, an optional input port set cannot be followed by a non-optional one.

Listing 15: Sample input ports XML segment

Listing 15 shows an example of what the input ports segment of the operator model looks like for a Join operator.

<inputPorts>
  <inputPortSet>
    <tupleMutationAllowed>false</tupleMutationAllowed>
    <windowingMode>Windowed</windowingMode>
    <windowPunctuationInputMode>WindowBound</windowPunctuationInputMode>
    <cardinality>2</cardinality>
    <optional>false</optional>
  </inputPortSet>
</inputPorts>