C++ primitive operator guide

This guide demonstrates creating a C++ primitive operator, including implementing the operator and testing the operator.

This guide uses an example that creates a C++ primitive operator to print a hello greeting for a set of names.

Implementing the C++ primitive operator

This section guides you through the steps of creating the primitive operator and configuring the code generator templates for your C++ primitive operator.

Creating the C++ primitive operator

This task demonstrates how to create the C++ primitive operator. This creates an operator model that describes the syntactic and semantic properties common to all instances of the operator.

Add your Streams 5.5 instance to the Streams Explorer in VS Code if you haven’t already.
Bring up the Command Palette and select Create C++ Primitive Operator.
Provide the following information:
- Project folder path: Use the Browse… button to create and select an empty folder on your machine called MyCppProject. The primitive operator files will be created in this folder. Example: /Users/someuser/Documents/streams/MyCppProject.
- Operator namespace: Specify sample.hello as the namespace. Your C++ primitive operator will be created in this namespace.
- Operator name: Specify MyCppOp as the name of your C++ primitive operator.
- Generic operator: Deselect the checkbox.
Click the Create button to create the skeleton C++ primitive operator.
If you have multiple Streams instances, you will be prompted to select an instance.

Customizing the code generator templates

This task demonstrates how to customize the code generator templates (.cgt files) for your C++ primitive operator. The code generator templates implement the operator logic.

Open the CPP code generator template MyCppOp_cpp.cgt. This is located in the MyCppProject/sample.hello/MyCppOp folder.
Enter the following using directive at the beginning of the file:
```
using namespace std;
```

Locate the process(Tuple & tuple, uint32_t port) method and enter the following code (in between the curly braces):

// List of names
string names [] = {"Emma", "Liam", "Olivia", "Noah", "Ava", "William"};

// Get the "nameIndex" attribute from the tuple
uint32_t const nameIndex = tuple.getAttributeValue("nameIndex");

// Get the name based on the nameIndex
string name = names[nameIndex];

// Generate the greeting here
string str = "Hello there, " + name;

// Set the generated greeting to the "hello" attribute in the tuple
ValueHandle handle0 = tuple.getAttributeValue("hello");
rstring & helloString = handle0;
helloString = str;

// Send the tuple along
submit(tuple, 0);

Select File > Save to save the changes to MyCppOp_cpp.cgt.

At this point, your C++ primitive operator folder should have the following structure:

/+ MyCppProject
   /+ sample.hello
      /+ MyCppOp
         /+ MyCppOp.xml
         /+ MyCppOp_cpp.cgt
         /+ MyCppOp_cpp.pm
         /+ MyCppOp_h.cgt
         /+ MyCppOp_h.pm
   /+ Makefile

Watch and learn: This video demonstrates how to create the C++ primitive operator.

Testing the C++ primitive operator

This section guides you through the steps of building your C++ primitive operator, creating a SPL application that invokes your operator, and then building and running the application to test your operator.

Building the C++ primitive operator

This task demonstrates how to build the C++ primitive operator. This creates a toolkit that you can use in your SPL application.

Right-click on the MyCppOp_cpp.cgt file and select Build C++ Primitive Operator.
If you have multiple Streams instances, you will be prompted to select an instance.
Check the notifications and build output to confirm that the primitive operator was built successfully. If it was successful, select the Add Toolkit to Toolkit Path button in the notification that appears. If you do not have a toolkit path specified, you will be prompted to specify a path. This makes the toolkit available for use in streaming applications.

Watch and learn: This video demonstrates how to build the C++ primitive operator to create a toolkit.

Creating the SPL application

This task demonstrates how to create a SPL application that invokes the C++ primitive operator.

Bring up the Command Palette and select Create SPL Application.
Provide the following information:
- Application folder path: Select an empty folder on your machine called TestCppProject. Example: /Users/someuser/Documents/streams/TestCppProject.
- Namespace: Specify sample.hello.test as the namespace. Your main composite will be created in this namespace.
- Main composite name: Specify Main as the name of your main composite.
Add the toolkit as a dependency.
1. Open the toolkit information model file info.xml. This is located in the TestCppProject folder.
2. Locate the <info:dependencies/> element and replace it with the following code:
```
<info:dependencies>
  <info:toolkit>
    <common:name>MyCppProject</common:name>
    <common:version>1.0.0</common:version>
  </info:toolkit>
</info:dependencies>
```

Edit the SPL source.

Open the SPL source file Main.spl. This is located in the TestCppProject/sample.hello.test folder.
Enter the following use directive at the beginning of the file after namespace sample.hello.test;:
```
use sample.hello::MyCppOp;
```

Enter the following code for the Main composite (replace the starter code in between the curly braces):

graph
  stream<rstring hello, uint32 nameIndex> InStream = Beacon() {
    logic
      state:
        mutable uint32 n = 0;
    param
      iterations: 6u;
    output
      InStream: hello = "", nameIndex = n++;
  }

  // Invoke the C++ primitive operator MyCppOp
  stream<InStream> Hello = MyCppOp(InStream) {}

  () as PrintHello = Custom(Hello) {
    logic
      onTuple Hello:
        println(hello);
  }

Select File > Save to save the changes to Main.spl.

Watch and learn: This video demonstrates how to create the SPL application.

Building and running the SPL application

This task demonstrates how to build and run the SPL application to test your C++ primitive operator.

Build and run the SPL application.
1. Right-click on the Main.spl file and select Build and Submit Job.
2. If you have multiple Streams instances, you will be prompted to select an instance.
3. When the build completes successfully, you will be prompted to configure the job submission. Accept the defaults by clicking on the Submit job button.
4. Check the notifications and submission output to confirm that the SPL application was submitted successfully. Take a note of the job ID.
Verify that your C++ primitive operator is working as expected.
1. Bring up the Streams Explorer and locate the new job in the Instances section.
2. Hover over the job and click on the Download Job Logs button.
3. Select a folder on your machine where the job logs will be downloaded to.
4. Unpackage the job logs .tar.gz file and open the PE output file pec.pe.<pe-id>.stdouterr. This is located in app-X/jobs/<job-id>.
5. Verify that the output shows a series of "Hello there, <name>" messages.
```
"Hello there, Emma"
"Hello there, Liam"
"Hello there, Olivia"
"Hello there, Noah"
"Hello there, Ava"
"Hello there, William"
```
After you have verified the result, cancel the running job.
1. Bring up the Streams Explorer and locate the job in the Instances section.
2. Hover over the job and click on the Cancel Job button.

Watch and learn: This video demonstrates how to build and submit the application.