Using Control Stream Features

When a StreamBase Server sbd process starts up (with or without an application), a container named system is always added. There are several system streams within an sbd, as listed in The System Container.

This page discusses features of the control stream in the system container that are of use when designing highly available StreamBase applications.

Tuples emitted from the control stream's output port in response to certain system-level events. These tuples have the following schema:

Whenever the leadership status of a StreamBase Server changes, an announcement tuple is sent on the control stream, with the param0 field containing either LEADER or NON_LEADER. When designing a highly available StreamBase application, you can monitor the system container's control stream to determine a server's current leadership status, and to react in some way if the status changes. For example, a monitoring application might add or remove a container, or dynamically enable or disable dequeuing or enqueuing for a container when the leadership status changes.

The following StreamSQL example application demonstrates how to set and query a dynamic variable to the current leadership status. The same functionality can be implemented in an EventFlow application as well.

-- leadership.ssql
--
-- Create an input stream connected from the system container's
-- control stream. When this application is added, we need to ensure that
-- this control stream is connected to the system.control stream.
--
create input stream control(subsystem string(30), 
                            id int, 
                            param0 string(50),
                            param1 string(50),
                            param2 string(50));

--
-- Declare a dynamic variable named "LEADER" which is initially set
-- to the value returned by the function getLeadershipStatus() and
-- is updated by the control stream
--
declare LEADER string(50) default getLeadershipStatus() update from 
     (select param0 from control where subsystem = "HA" and id = 0);

--
-- Create an input stream so that we can return the value of the
-- dynamic variable
--
create input stream CheckLeaderInputStream (ping int);

--
-- The output for the dynamic variable query
--
create output stream IsLeaderOutputStream as
   select LEADER from CheckLeaderInputStream;

For this example application to work, it must have a container connection from the system container's control output stream to the input stream of this module. You can add this application to a container named leader with the following example command:

sbadmin addContainer leader leadership.ssql leader.control=system.control

The CONTAINER subsystem of the system container's control stream sends an announcement tuple each time a container is started. The event tuple is sent exactly once for each instance of a container start. For example, when a container named app4 is first added to a server, an event tuple is generated on the control stream announcing that container app4 has been started. If app4 is removed and re-added, another event tuple is sent.

You can take advantage of the container start event to perform special processing on the startup of a container. The following StreamSQL example application demonstrates how to set a dynamic variable stating whether or not the start container event has been sent. The same functionality can be implemented in an EventFlow application as well.

-- starttuple.ssql
--
-- Create an input stream connected from the system container's
-- control stream. When this application is added, we need to ensure that
-- this control stream is connected to the system.control stream.
--
create input stream control(subsystem string(30), 
                            id int, 
                            param0 string(50),
                            param1 string(50),
                            param2 string(50));

--
-- Declare a dynamic variable named "GOT_START_TUPLE" which is initially set
-- to false. When we get a start tuple for this container, we change the 
-- value to true.
--
declare GOT_START_TUPLE boolean default false update from 
     (select true as start from control where subsystem = "CONTAINER" 
      and id = 0 and param0 = getContainer());

--
-- Create an input stream so that we can return the value of the
-- dynamic variable
--
create input stream CheckGotStartTupleInputStream (ping int);

--
-- The output for the dynamic variable query
--
create output stream GotStartTupleOutputStream as
   select GOT_START_TUPLE from CheckGotStartTupleInputStream;

Like the example above, this application must have a container connection from the system.control stream to its input stream, also named control. Use a command like the following to add this application to a container named starttuple:

sbadmin addContainer starttuple starttuple.ssql starttuple.control=system.control