Buffering Sample

Contents

Introduction
Importing This Sample into StreamBase Studio
Running the Buffering Sample Application
This Sample's Files
Sample Location

Introduction

This sample demonstrates the throughput benefit of using buffering in StreamBase client programs, and demonstrates how buffering effects latency. The sample application contains an aggregate that calculates the average, minimum, and maximum elapsed time from the point the tuple was updated and sent from the client until it was processed by the StreamBase application. This elapsed time can be thought of as the client enqueue latency. The latency is reported in microseconds, but the Java client latency is calculated using nanoseconds. The C++ sample client is calculated using milliseconds.

For related information about enabling buffering in producer or enqueue clients, see Developing StreamBase Client Applications.

Note

The Java code in this sample is delivered only in source code form. To build the code, you must load the sample into StreamBase Studio, which automatically builds the Java code.

Importing This Sample into StreamBase Studio

In StreamBase Studio, import this sample with the following steps:

  • From the top-level menu, select File>Import Samples and Community Content.

  • Enter buffering to narrow the list of options.

  • Select Shows buffering features in clients from the Client Libraries category.

  • Click Import Now.

StreamBase Studio creates a single project containing the sample files.

Running the Buffering Sample Application

The Java version of this sample is intended to be run in StreamBase Studio, while the C++ version is intended to be run in UNIX terminal windows or Windows Command Prompt windows.

The sample has no provision for running the Java version at the command line, but experienced Java developers can do so by adding the java-bin directory to the classpath.

Introduction and Setup

When you load this sample in Studio, the sample places a launcher for the Java enqueuer program into Studio's Run History list. The overall procedure is:

  • Run the StreamBase application, simple.sbapp, in Studio. The StreamBase application accepts input from the Manual Input or Feed Simulations view, and shows output in the Output Streams view, as normal.

  • Use the launcher in the Run History list to run the Enqueuer Java client program at the same time the StreamBase application is running.

  • Watch the results in the Output Streams view.

Run the Java client launcher from the Run History list using one of the following methods:

  • From the Studio top-level menu, invoke Run>Run History, and select the specified launcher from the list.

  • Open the Run Configurations dialog, select the specified launcher from the Java application category, then click Run.

  • Click the down-arrow next to the Run button in the Studio toolbar, and select the specified launcher from the list.

The Java client launcher placed in the Run History list presumes that Studio is running the StreamBase application on port 10000, which is the installed default port for StreamBase application launches. Before you proceed, use these steps to confirm that port 10000 is the default launch port:

  1. Open Windows>Preferences.

  2. In the left side navigation column, open StreamBase Studio>Test/Debug.

  3. Confirm that the Default Port setting is 10000. If not, change it to 10000.

  4. Click Apply and Close.

Steps to Run in Studio

Follow these steps to run this sample in StreamBase Studio:

  1. Open the src/main/eventflow/packageName folder.

  2. Double-click to open the simple.sbapp application. Make sure the application is the currently active tab in the EventFlow Editor.

  3. Click the Run button. This opens the SB Test/Debug perspective and starts the module.

  4. Open the Run History list as described in Introduction and Setup, and select the Enqueuer launcher. This runs the Enqueuer.java program, which connects to the StreamBase Server instance running simple.sbapp and sends data to its input ports.

  5. Watch the Output Streams view in Studio, which shows average, minimum, and maximum latency numbers every second while data is enqueued. The Console view reports the output of the Enqueuer program, which is the number of tuples enqueued and the number of tuples enqueued per second.

  6. In the Debug view, right-click the Enqueuer line, and select Edit Enqueuer from the context menu. In the Arguments tab, change the -b10 entry to -b1000, and click Run. Experiment with other settings and re-run, as desired. (Run Enqueuer -h at the command prompt, or read the Java source code, to see the options for the Enqueuer program.)

  7. When done, press F9 or click the Terminate EventFlow Fragment button. This closes both the StreamBase application and the Enqueuer program.

Steps to Run the C++ Buffering Sample

To run the C++ buffering sample:

  1. Open three terminal windows on UNIX, or three StreamBase Command Prompts on Windows. In each window, navigate to your workspace copy of the sample, as described above.

  2. On Windows, in window 1, copy Enqueuer.exe from streambase-install-dir\sample\buffering to the current directory.

  3. In window 1, run StreamBase Server and the sample application:

    sbd simple.sbapp

  4. In window 2, start a dequeue session from the output stream with this command:

    sbc dequeue

  5. In window 3, run the C++ client application. For UNIX:

    ./Enqueuer -b 10

    For Windows:

    Enqueuer -b 10

  6. In window 3, after a short delay for processing, look for the number of tuples enqueued and the number of tuples enqueued per second. In window 2, look for average, minimum, and maximum latency numbers every second while data is enqueued.

  7. Run the Enqueue program again using -b 1000 instead of -b 10 and observe the increased throughput and also the higher average latency.

  8. Command line options can be given to each of the enqueuers. The following commands displays those options:

    Enqueuer -h

  9. In window 3, type the following command to terminate the server and dequeuer:

    sbadmin shutdown

This Sample's Files

The Buffering sample consists of the files shown in the following table.

File Description
simple.sbapp A simple StreamBase application that maps times in two input streams to elapsed milliseconds, combines the streams with a Union operator, and then aggregates the stream of doubles in one-second windows to compute minimum, maximum and average latency values.
Enqueuer.java Java source code for the client enqueuer program, placed in the com.streambase.sample.buffering package in src/main/java/ and automatically compiled by Studio.
Enqueuer.launch A Studio launcher for the Java enqueuer programs. The presence of the .launch file is what places the launcher in the Run History list.
Enqueuer.cpp C++ source code for the client enqueuer program.
Enqueuer UNIX only. Executable client enqueuer program built from the C++ source code.
Makefile UNIX only. A makefile to build and run the client program from C++ source code on UNIX.
*.exe Windows only. Executable client programs built from the C++ source code.
*.sln, *.vcproj Windows only. Solution and project files for Visual Studio. Use these files with Visual Studio to rebuild the C++ client programs.

Note

In the Visual Studio project files, the paths to the StreamBase Include files and libraries are configured for the standard default StreamBase installation directory. You may need to adjust these paths for your installation.

Sample Location

When you load the sample into StreamBase® Studio, Studio copies the sample project's files to your Studio workspace, which is normally part of your home directory, with full access rights.

Important

Load this sample in StreamBase® Studio, and thereafter use the Studio workspace copy of the sample to run and test it, even when running from the command prompt.

Using the workspace copy of the sample avoids permission problems. The default workspace location for this sample is: 

studio-workspace/sample_buffering

See Default Installation Directories for the default location of studio-workspace on your system.