Using the Metronome Operator

This topic describes the actions you can take on each tab of the Metronome operator's Properties view.

Introduction

The Metronome delivers output tuples periodically based on the system clock, at an interval that you specify. In the same way that a musician's metronome can be used to indicate the exact tempo of a piece of music, you can use the StreamBase Metronome operator to control the timing of downstream operations by a connected component.

For example, the following EventFlow module (from the Operator Sample Group shipped with StreamBase) is configured with a Metronome operator set to emit a timer tuple every five seconds.

In effect, the Read operation of the connected ReadAllRows Query operator occurs at that interval. The Read operation is a lookup of the current share Price from the NameValuePairs Query Table.

A Metronome operator does not receive any input tuples, has zero input ports, and therefore does not pay attention to timestamp fields. Each Metronome operator has one output port. Unlike the related Heartbeat operator, the Metronome operator does not provide a slack property, which means there is no variance in the emit interval for each timer tuple.

Use the Maximum tuples to output field to limit the duration of emitted tuples. This field allows a Metronome operator to emit a tuple periodically, then stop emitting altogether when the specified limit is reached.

Specify a number or an expression that evaluates to seconds for the Tuple output interval property. You can can also enter this value as a parameter in the form ${parameter} or specify a defined constant.

To disable a Metronome operator (prevent it from firing), set the value for Tuple output interval to 0.

The Metronome operator fires at even multiples of the specified interval after the Unix epoch. Thus, for an interval of 7 seconds, the first tuple can only occur at exactly 7 seconds after the hour if the hour boundary was itself a multiple of 7 seconds (which means a multiple of 7 hours) since Jan 1 1970 00:00:00 GMT. In practice, this means that the difference between module startup time and the moment a Metronome operator sends its first tuple is arbitrary, but is never longer than the specified interval. Thereafter, the operator sends tuples at the specified interval.

You might need to use a Metronome operator to activate a sequence in your StreamBase application on a periodic basis, for example to slow the pace of an output stream to a consuming application that cannot process data as fast as the StreamBase server is able to deliver it.

When the StreamBase server is very busy or when downstream operators cannot consume tuples at the output rate, output from a Metronome operator can be delayed. This is most likely to occur with very short output intervals, say less than 100ms. If the delay is longer than the output interval, output tuples can back up. When the Metronome operator is next serviced, more than one tuple will be emitted together unless you enable the check box labeled Drop tuples delayed longer than the output interval. If you select that option, only the most recent queued tuple is emitted; any others waiting to be issued are dropped.

A StreamBase module can have one or more Metronome operators, each with different timing values. You can also have a StreamBase module that uses one or more Metronome operators plus one or more Heartbeat operators. Think of a StreamBase Heartbeat operator as another type of timing mechanism. Unlike the Metronome operator, a Heartbeat operator's pulse can vary (like a person's beating heart, which can speed up or slow down). You can specify the amount of variance or slack that is allowed by the Heartbeat operator.

Properties: General Tab

Name: Use this field to specify or change the component's name, which must be unique in the application. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports and Error Streams to learn about Error Ports.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Properties: Output Settings Tab

The Output Settings tab allows you to specify:

Tuple output interval

Specifies how often a timer tuple is to be emitted to the next downstream component. You can enter integers or decimal values such as .10, meaning ten times per second. The lowest supported granularity is 10 milliseconds, or .01, meaning 100 times per second. If you enter a value lower than .01, such as .009, StreamBase Studio displays the following error:

The Tuple Output Interval you entered may be too fine-grained to be guaranteed.

If you enter 0 (zero), or a number below .0005 (which effectively rounds to zero), StreamBase Studio displays the following error:

The Tuple Output Interval must be a numeric value greater than zero.
Output field name

Specifies the name of the single field that will comprise the timer tuple. The type is always a timestamp, and the value is always the current time when each Metronome tuple is emitted.

Properties: Concurrency Tab

Use the Concurrency tab to specify the use of parallel regions for this instance of this component. Consider selecting the parallel regions check box if this component instance is long-running or compute-intensive, can run without data dependencies on other StreamBase components, and would not cause the containing module to block while waiting for a thread to return. In this case, you may be able to improve performance by selecting this option. This option directs StreamBase Server to process this component concurrently with other processing in the application. The operating systems supported by StreamBase automatically distribute the processing of threads across multiple processors.

Caution

The parallel regions setting is not suitable for every application, and using this setting requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.