Output ports

The outputPorts element describes the output configurations of an operator.

Listing 16: The output ports type

Listing 16 gives the basic structure.

<xs:complexType name="outputPortsType">
  <xs:sequence>
    <xs:element name="outputPortSet" type="outputPortSetType" minOccurs="0" maxOccurs="unbounded"/>
    <xs:element name="outputPortOpenSet" type="outputPortOpenSetType" minOccurs="0" maxOccurs="1"/>
  </xs:sequence>
</xs:complexType>
          
<xs:complexType name="outputPortOpenSetType">
  <xs:sequence>
    <xs:element name="description" type="common:descriptionType" minOccurs="0" maxOccurs="1"/>
    <xs:element name="expressionMode" type="expressionModeType"/>
    <xs:element name="autoAssignment" type="xs:boolean"/>
    <xs:element name="completeAssignment" type="xs:boolean"/>
    <xs:element name="rewriteAllowed" type="xs:boolean"/>
    <xs:element name="outputFunctions" type="outputFunctionsType" minOccurs="0" maxOccurs="1"/>
    <xs:element name="windowPunctuationOutputMode" type="outputPunctuationModeType"/>
    <xs:element name="windowPunctuationInputPort" type=xs:integer" minOccurs="0" maxOccurs=1"/>
    <xs:element name="finalPunctuationPortScope" type="optionalPortScopeType" 
                minOccurs="0" maxOccurs="1"/>
    <xs:element name="tupleMutationAllowed" type="xs:boolean"/>
    <xs:element name="outputAssignmentPortScope" type="portScopeType" minOccurs="0" maxOccurs="1"/>
    <xs:element name="allowNestedCustomOutputFunctions" type="xs:boolean" 
                minOccurs="0" maxOccurs="1"/>
 </xs:sequence>
</xs:complexType>
            
<xs:complexType name="outputPortSetType">
  <xs:complexContent>
    <xs:extension base="outputPortOpenSetType">
    <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:complexTypename="outputFunctionsType">
  <xs:sequence>
    <xs:element name="default" type="xs:string"/>
    <xs:element name="type" type="xs:string"/>
  </xs:sequence>
</xs:complexType>
                
<xs:simpleTypename="outputPunctuationModeType">
  <xs:restrictionbase="xs:string">
    <xs:enumeration value="Generating"/>
    <xs:enumeration value="Free"/>
    <xs:enumeration value="Preserving"/>
  </xs:restriction>
</xs:simpleType>

<xs:complexType name="optionalPortScopeType">
  <xs:sequence>
    <xs:element name="port" type="xs:integer" minOccurs="0" maxOccurs="unbounded"/>
  </xs:sequence>
</xs:complexType>

Output ports are defined in terms of port sets, just like input ports. A port set is a fixed number of ports that share a configuration. This sharing 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 outputPorts element contains zero or more outputPortSet elements, followed by an optional outputPortOpenSet element.

The structure of an output port open set, as the output port set extends from the open variant, has several elements. The expressionMode element describes the valid syntax of the attribute assignments that are made on this port. An expressionMode value of CustomLiteral is not valid for output ports and results in a compilation error. Valid values for the expression mode are:

Attribute: Means that the assignments made to output attributes of this port need to be stream attributes. For example: output Out : x = In.y;, but not x = In.y.z.
AttributeFree: Means that the assignments made to output attributes of this port cannot reference any input stream attributes. For example: output Out : x = 3 + random(3);, but not x = In.x + 3.
Constant: Means that the assignments made to output attributes of this port need to be compile-time evaluatable to a constant. For example: output Out : x = 3 + pow(2, 3);, but not x = random(3).
Expression: Is the most flexible expression mode. Any SPL expression of correct type can appear as an assignment to the output attributes of this port. For example: output Out : x = A.y + B.z;.
Nonexistent: Means that output attribute assignments cannot be specified in the SPL source for this port.

The autoAssignment element defines whether unassigned attributes are automatically assigned from the attributes of the input ports. If set to true, the SPL compiler rewrites (at compile time) the operator invocation as if the unassigned output attributes have explicit assignments in the output section. For each output attribute that is missing an assignment, an input attribute that has the same name and type, or that has the same name and type T, where the output attribute type is optional<T>, is assigned to it. If there is no such input attribute, an error is reported at compile time. An expressionMode value of Constant is incompatible with an autoAssignment value of true. This combination results in a compilation error.

The completeAssignment element defines whether all the output port attributes need to be assigned to have a valid invocation of the operator. This element is checked at compile time. If an operator has this element set to true in its operator model and if not all output attributes have assignments after the auto-assignment step (if requested) for a given instance of this operator, an error is reported.

The rewriteAllowed element specifies whether the compiler is allowed to rewrite the expressions that appear in the output attribute assignments for this port.

The outputFunctions element defines the valid custom output functions that can appear in output attribute assignments. It is optional. When present, it contains two subelements: the type element, which defines the name of the custom output function type, as in RelationalAggs; and the default element, which defines the default output function to be used when auto-assignment of output attributes is performed. The default value should be a valid function name for the custom output function type that is being used (as in Last for RelationalAggs). If the user code specifies an output attribute assignment without an output function for a port that expects an output function, the default output function is inserted automatically.

The finalPunctuationPortScope element, which is optional, specifies the set of input ports to be used by the SPL language run time for final punctuation forwarding. By default, operators that have both input and output ports automatically forward final punctuation from their input ports to their output ports. They generate final punctuation on an output port when final punctuation is received on all input ports. The finalPunctuationPortScope can be used to limit the set of input ports to be used for forwarding the final punctuation. This element can also be used to turn off auto-forwarding of final punctuation, by setting the set of input ports to use for forwarding to the empty set. In this case, the operator developer is responsible for ensuring that the output port gets final punctuation.

The windowPunctuationOutputMode specifies the window punctuation semantics of the output port. The options are:

Generating - This port generates window punctuation.
Free - This port is free of window punctuation.
Preserving - This port preserves the received window punctuation. If an operator has more than one input port, then the windowPunctuationInputPort element must be specified in order to identify which input port's punctuation is being preserved.

The windowPunctuationInputPort element associates an input port with a punctuation-preserving output port. This element can be specified only if the output port's window punctuation mode is Preserving. The windowPunctuationInputPort can be set to -1, which has the same semantics as a missing windowPunctuationInputPort element. It is important to note that punctuation forwarding for window punctuation is not performed automatically by the SPL language run time (unlike final punctuation) and the operator model is used to inform the SPL compiler about the behavior that is being implemented by the operator.

The tupleMutationAllowed element defines whether this operator allows the downstream operators to mutate the output tuples that are submitted to this port by the submit call. If set to true, then the processing logic of the operator should expect that the tuples it submits to this port are modified as a result of the submit call. The outputAssignmentPortScope optionally limits, which input port attributes can appear in output assignments on this port. If a scope is specified, only attributes from the ports that are specified by the scope can appear in the output assignments for that port.

The allowNestedCustomOutputFunctions element controls whether custom output functions are allowed only at the top level of an output clause (for example, output A : a = fcn()) or whether they are allowed anywhere in the expression (for example, output A : a = fcn() + 5). The allowNestedCustomOutputFunctions element is most useful when used with SPLExpressionTreeMode, allowing a primitive C++ operator to examine the output clause expression to decide how to generate C++ code. The default value is false, if allowNestedCustomOutputFunctions is not present.

An output port set contains two additional elements on top of what is included in an output 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 output port set cannot be followed by a non-optional one.

Listing 17: Sample output ports XML segment

Listing 17 shows an example of what the output ports segment of the operator model looks like for a Split operator.

<outputPorts>
  <outputPortSet>
    <expressionMode>Expression</expressionMode>
    <autoAssignment>true</autoAssignment>
    <completeAssignment>true</completeAssignment>
    <rewriteAllowed>true</rewriteAllowed>
    <windowPunctuationOutputMode>Preserving</windowPunctuationOutputMode>
    <tupleMutationAllowed>true</tupleMutationAllowed>
    <cardinality>1</cardinality>
    <optional>false</optional>
  </outputPortSet>
  <outputPortOpenSet>
    <expressionMode>Expression</expressionMode>
    <autoAssignment>true</autoAssignment>
    <completeAssignment>true</completeAssignment>
    <rewriteAllowed>true</rewriteAllowed>
    <windowPunctuationOutputMode>Preserving</windowPunctuationOutputMode>
    <tupleMutationAllowed>true</tupleMutationAllowed>
  </outputPortOpenSet>
</outputPorts>