Home
Developing
Learn about different Teracloud Streams tools and features to write, compile, run, and test streams applications.
Developing custom operators
Create custom operators if shipped toolkits do not provide the necessary logic or behavior needed for your stream applications.
Best practices
Use these tips to write operators that perform effectively in their application, and in other applications.
Control ports
Control ports are operator input ports that receive tuples that update the internal operator state. These ports do not generate output tuples through submit() calls. Control ports are useful to dynamically control the behavior of the operator by changing a filtering condition, for example.

Welcome
Learn about the core capabilities of Teracloud® Streams, its architecture, and key concepts.
Installing
Use this information to install, upgrade, and uninstall the Teracloud® Streams product.
Configuring
Create a basic or an enterprise domain which is a single point for configuring and managing common resources, security, and instances.
Administering
Administer the product by using the Teracloud® Streams graphical user interface, APIs, or the streamtool command-line interface.
Developing
Learn about different Teracloud Streams tools and features to write, compile, run, and test streams applications.
- Development concepts
  Development of stream applications consists of several components such as operators, streams, tuples, Streams Processing Language, toolkits, and more.
- Developing stream applications
  Try out tutorials and explore details about stream application development, SPL features, and best practices.
- Developing native functions
  Extend SPL's computational capabilities by creating native functions written in C++ or Java.
- Developing custom operators
  Create custom operators if shipped toolkits do not provide the necessary logic or behavior needed for your stream applications.
  - Types of operators
    When developing new operators, developers need to choose the kind of operator to implement based on the task they want to accomplish, the programming language they want to use and the trade-offs they are willing to make between generality and ease of implementation.
  - Primitive operator artifacts
    Each primitive operator is stored in a directory whose name follows the format ([:alnum:]+\.)*[:alnum:]+ where the last part ([:alnum:]+) is the operator name.
  - Developing primitive operators
    You develop new primitive operators by implementing them in the C++ or Java™ language. You must define an operator model that describes the syntax and semantics of the operator and implement the operator logic by creating the header and implementation code generator templates.
  - Creating C++ libraries for operators and native functions
    To enable operators and native functions, you must compile with the appropriate include file paths and options and link any shared libraries against the correct runtime libraries.
  - Best practices
    Use these tips to write operators that perform effectively in their application, and in other applications.
    - Window support
      When you write a primitive operator, you might need to maintain a set of recently processed input tuples to compute the operator output. It might be sufficient to use Streams Processing Language (SPL) support for windows.
    - Operator naming conventions
      Operators perform a specific, limited function and are available for programmer use in the toolkits. Along with streams, operators are the most fundamental concept in the Streams Processing Language (SPL).
    - Custom output functions
      Custom output functions are operator-specific routines that can be called from the output clause of an operator.
    - Stream punctuation
      Punctuation marks are an in-band signals that are inserted between tuples in a stream. They indicate breaks in the data, which can be used by the operator logic.
    - Control ports
      Control ports are operator input ports that receive tuples that update the internal operator state. These ports do not generate output tuples through submit() calls. Control ports are useful to dynamically control the behavior of the operator by changing a filtering condition, for example.
    - Default values for operator parameters
      Operators that accept optional parameters at their invocation site must provide default values or require the parameter to be provided. Choose default values that are safe, that do not adversely affect performance, and that follow the principle of least surprise.
  - Performance recommendations
    These tips help you to improve performance of your primitive operators in C++.
- Developing custom toolkits
  Bundle and reuse custom functions and operators across several stream applications by creating custom toolkits.
- Working with files
  Applications and operators can read and write to files in several ways. If relative paths are used, the data directory is used as the root of relative paths. To enable logic to access the runtime application or toolkit directory hierarchies, language-specific functions can be used.
- Enabling Streams data exchange
  Teracloud® Streams provides a data exchange REST API for inserting and retrieving tuples within a job to easily integrate with other data services and external applications. Stream applications can enable the data exchange feature by using one or more Endpoint operators.
- Debugging stream applications
  Debug stream applications using the interactive, command line-based Streams Debugger (sdb).
Troubleshooting
Resolve problems with Teracloud® Streams using the troubleshooting tools provided with the product as well as the resources offered by Teracloud Support.
Reference
Find details on the SPL language, toolkits, APIs, commands, and more.
Glossary
Use this glossary to find terms and definitions for Teracloud® Streams.

Control ports

Control ports are operator input ports that receive tuples that update the internal operator state. These ports do not generate output tuples through submit() calls. Control ports are useful to dynamically control the behavior of the operator by changing a filtering condition, for example.

Operator control ports often consume streams that are generated by other operators downstream, effectively configuring a loop in the application flow graph. By configuring an input port as a control port, the developer informs the Streams Processing Language (SPL) compiler that possible feedback loops using this port are safe. That is, they do not lead to deadlocks or stack overflow due to infinite recursion. Infinite recursion occurs when operators with feedback loops are fused; when the operator submits a tuple to its output port, the subsequent submit() calls lead to a loop of other submit() calls, effectively overflowing the call stack. By default, the SPL compiler assumes that a declared input port is a data port, not a control port.

When you develop a primitive operator that contains control ports, declare data ports first and control ports second. An example is the Gate operator from the SPL Standard Toolkit. In this operator, the first port is a data port, and the second port is a control port. Consider this code sample that shows a segment of the Gate operator model, where the second input port is configured as control (line 16).

01: <inputPorts>
02:  <inputPortSet>
03:    <description>Port that ingests tuples to be gated</description>
04:    <tupleMutationAllowed>false</tupleMutationAllowed>
05:    <windowingMode>NonWindowed</windowingMode>
06:    <windowPunctuationInputMode>Oblivious</windowPunctuationInputMode>
07:    <cardinality>1</cardinality>
08:    <optional>false</optional>
09:   </inputPortSet>
10:   <inputPortSet>
11:     <description>Port that ingests tuples
12:         controlling the gate</description>   
13:     <tupleMutationAllowed>false</tupleMutationAllowed>
14:     <windowingMode>NonWindowed</windowingMode>
15:     <windowPunctuationInputMode>Oblivious</windowPunctuationInputMode>
16:     <controlPort>true</controlPort>
17:     <cardinality>1</cardinality>
18:     <optional>false</optional>
19:   </inputPortSet>
20: </inputPorts>