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.
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.
In StreamBase Studio, import this sample with the following steps:
From the top menu, select→ .
bufferingfrom the Client Libraries category.
StreamBase Studio creates a project for this sample.
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.
StreamBase Systems strongly recommends that you load this sample in Studio, and thereafter use the 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 the permission problems that are
inevitable when trying to work with the installed location in
C:\Program Files or
The default workspace location for this sample is:
See Default Installation
Directories for the location of
studio-workspace on your system.
In the default StreamBase installation, this sample's files are installed in:
See Default Installation
Directories for the location of
streambase-install-dir on your system. This location
usually requires administrator privileges for write access.
The Buffering sample consists of the files shown in the following table.
||A simple StreamBase application with a Map operator that negates its incoming int and double fields, and adds "processed" to its incoming string fields. The input schema includes a field of type tuple with a nested tuple field.|
Java source code for the client enqueuer program, placed in
A Studio launcher for the Java enqueuer programs. The presence of the
||C++ source code for the client enqueuer program.|
||UNIX only. Executable client enqueuer program built from the C++ source code.|
||UNIX only. A makefile to build and run the client program from C++ source code on UNIX.|
||Windows only. Executable client programs built from the C++ source code.|
Windows only. Solution and project
files for Visual Studio. Use these files with Visual Studio to rebuild the
C++ client programs.
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.
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.
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 Application Output view, as normal.
Use the launcher in the Run History list to run the
EnqueuerJava client program at the same time the StreamBase application is running.
Watch the results in the Application Output view.
Run the Java client launcher from the Run History list using one of the following methods:
From the Studio top-level menu, invoke→ , and select the specified launcher from the list.
Open the Run Configurations dialog, select the specified launcher from the Java application category, then click.
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:
In the left side navigation column, open→ .
Confirm that the Default Port setting is 10000. If not, change it to 10000.
Follow these steps to run this sample in StreamBase Studio:
In the Package Explorer, double-click to open the
simple.sbappapplication. Make sure the application is the currently active tab in the EventFlow Editor.
Click the Run button. This opens the SB Test/Debug perspective and starts the application.
Open the Run History list as described in Introduction and Setup, and select the
Enqueuerlauncher. This runs the
Enqueuer.javaprogram, which connects to the StreamBase Server instance running
simple.sbappand sends data to its input ports.
Watch the Application Output 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.
In the Debug view, right-click the Enqueuer line, and select Edit Enqueuer from the context menu. In the Arguments tab, change the
-b1000, and click . Experiment with other settings and re-run, as desired. (Run
Enqueuer -hat the command prompt, or read the Java source code, to see the options for the Enqueuer program.)
When done, press F9 or click the Stop Running Application button. This closes both the StreamBase application and the Enqueuer program.
To run the C++ buffering sample:
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.
On Windows, in window 1, copy
to the current directory.
In window 1, run StreamBase Server and the sample application:
In window 2, start a dequeue session from the output stream with this command:
In window 3, run the C++ client application. For UNIX:
./Enqueuer -b 10
Enqueuer -b 10
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.
Run the Enqueue program again using
-b 1000instead of
-b 10and observe the increased throughput and also the higher average latency.
Command line options can be given to each of the enqueuers. The following commands displays those options:
In window 3, type the following command to terminate the server and dequeuer: