IBM InfoSphere Streams Version 4.1.0

Operator ScheduledBeacon

SPL standard and specialized toolkits > com.ibm.streams.teda 1.0.2 > com.ibm.streams.teda.utility > ScheduledBeacon

Primitive operator image not displayed. Problem loading file: ../../image/tk$com.ibm.streams.teda/op$com.ibm.streams.teda.utility$ScheduledBeacon.svg

The ScheduledBeacon operator is a utility source that generates tuples on-the-fly. You can configure a schedule for tuple generation that is similar to the cron software utility.

The ScheduledBeacon operator has one output port and one optional input (control) port. Tuples that are received on the input port may change the schedule during operation.

You can configure a schedule by using the following schedule components and their valid values:

  • month (1 through 12)
  • day of month (1 through 31)
  • day of week (0 through 6 with 0=Sunday, 1=Monday, 2=Tuesday, and so on)
  • hour (0 through 23)
  • minute (0 through 59)
  • tensec (0 through 5)

A component value may be an asterisk (*), which stands for the complete range.

The operator supports ranges of numbers. A range is two numbers that are separated by a hyphen that include the two numbers and all the numbers between them. For example, 8-11 for an hour component specifies runs at hours 8, 9, 10, and 11.

The operator also supports lists. A list is a comma-separated set of numbers (or ranges) that include each of the elements in the list. For example, 1,2-5,9 for a day of the month specifies runs on days 1, 2, 3, 4, 5, and 9.

The component values must not contain any whitespace or character other than digits, hyphens, or commas.

If an empty schedule component is provided, the schedule is disabled, except for day of the month and day of the week, which both must be configured with empty strings to disable the schedule.

To determine when a tuple must be generated, all components are combined with a logical and conjunction, except for the day of the month (mday) and day of the week (wday). These schedule parameters are combined with a logical or conjunction.

The following logical operation generates a tuple:

sendTuple = (month==now) && ((mday==now) || (wday==now)) && (hour==now) && (minute==now) && (tensec==now)

This operator checks the schedule six times a minute at the beginning of each 10-second interval. Thus, the granularity of the schedule is 10 seconds. While the minimum granularity of the schedule is ten seconds and the operator tries to stick to that interval as close as possible, it may happen that the thread is blocked more than ten seconds for overloaded processors and thus may skip the submission of a tuple.

If an interval that should result in a tuple is skipped, the tuple is not sent. A tuple can be skipped because of overload, the operator not getting CPU, and slow downstream operators that block the submission of the previous tuple.

The following example sends a tuple at each half and full minute:

month:  "*";
wday:   "*";
hour:   "*";
minute: "*";
tensec: "0,3";

The following example sends a tuple 10 minutes past each hour between 7 AM and 10 AM and between 2 PM and 9 PM:

month:  "*";
wday:   "*";
hour:   "7-10,14-19";
minute: "10";
tensec: "0";

The following example sends a tuple at each half and full hour between 9 AM and 5 PM, from Monday through Friday:

month:  "*";
wday:   "1-5";
hour:   "9-17";
minute: "0,30";
tensec: "0";

You can set a schedule by specifying one of two parameter sets or a mix of both sets.

The first parameter set consists of month, mday, wday, hour, minute, and tensec and defines the initial schedule. These parameters are evaluated once during start-up. If the initial schedule is omitted or incomplete, the operator does not generate any tuples until a valid schedule is received from the optional input port.

The second parameter set consists of monthAttribute, mdayAttribute, wdayAttribute, hourAttribute, minuteAttribute, and tensecAttribute. The parameters specify the input attributes holding new values for the corresponding schedule components. If the new component values are valid, the previous values are overridden.

This operator does not allow any custom logic.

Behavior in a consistent region

Currently, IBM® InfoSphere® Streams does not allow an operator with a control port as its only input port to participate in a consistent region. As this momentarily is the only way to dynamically change the configuration of the ScheduledBeacon operator, supporting consistent region does not make sense now. Errors and warnings occur when you compile your streams processing application and use the operator in a consistent region.

Checkpointing

The operator supports checkpointing and restores its iteration count, month, mday, wday, hour, minute, tensec, and its nInvalidSchedules metric values. This allows to restore the last known configuration with a reset even when it was changed via the control port.

Summary

Ports
This operator has 1 input port and 1 output port.
Windowing
This operator does not accept any windowing configurations.
Parameters
This operator supports 15 parameters.

Optional: month, mday, wday, hour, minute, tensec, monthAttribute, mdayAttribute, wdayAttribute, hourAttribute, minuteAttribute, tensecAttribute, initDelay, initialTrigger, ignoreInvalidSchedule

Metrics
This operator reports 1 metrics.

Properties

Implementation
C++
Threading
Never - Operator never provides a single threaded execution context.

Input Ports

Ports (0)

This optional input port supplies a new schedule. The components for this new schedule are taken from input stream attributes. The names of these stream attributes are defined by using the monthAttribute, mdayAttribute, wdayAttribute, hourAttribute, minuteAttribute, and tensecAttribute parameters.

If the new schedule is invalid (because of a parsing or range error), an error is logged and the old schedule remains active.

Properties

Output Ports

Assignments
This operator allows any SPL expression of the correct type to be assigned to output attributes.
Output Functions
Functions
<any T> T AsIs(T)

The original argument expression is submitted.

public uint64 IterationCount()

The number of sent tuples. This function generates sequences of data with different values. The initial value is 0.

Example use:

submit {a=0, b=1}, {a=2, b=3}, ...

stream<int32 a, int32 b> A = ScheduledBeacon() {
   param ...
   output A : a = (int32) (IterationCount()*2ul), b = (int32) (IterationCount()*2ul+1ul);
}

Ports (0)

This mandatory output port sends the tuples.

Properties

Parameters

This operator supports 15 parameters.
month

The initial value of the month component. Valid values are 1 to 12, inclusive, with 1 equaling January, 2 equaling February, and so on. If the parameter is omitted, the schedule is disabled.

Properties

mday

The initial value of the day of the month component. Valid values are 1 to 31, inclusive. If this and the wday parameter are omitted, the schedule is disabled.

Properties

wday

The initial value of the day of the week component. Valid values are 0 to 6, inclusive, with 0 equaling Sunday and 6 equaling Saturday. If this and the mday parameter are omitted, the schedule is disabled.

Properties

hour

The initial value of the hour component. Valid values are 0 to 23, inclusive. If the parameter is omitted, the schedule is disabled.

Properties

minute

The initial value of the minute component. Valid values are 0 to 59, inclusive. If the parameter is omitted, the schedule is disabled.

Properties

tensec

The initial value of the ten seconds interval component. Valid values are 0 to 5. For example, a value of 1 equals 10 seconds, and a value of 5 equals 50 seconds. If the parameter is omitted, the schedule is disabled.

Properties

monthAttribute

The name of the input attribute that updates the month component. Valid values are 1 to 12, inclusive, with 1 equaling January and 12 equaling December. The parameter is allowed only if the optional input port exists. If this parameter is omitted, the month component is not updated.

Properties

mdayAttribute

The name of the input attribute that updates the day of the month component. Valid values are 1 to 31, inclusive. This parameter is allowed only if the optional input port exists. If this parameter is omitted, the day of the month component is not updated.

Properties

wdayAttribute

The name of the input attribute that updates the day of the week component. Valid values are 0 to 6, inclusive, with 0 equaling Sunday and 6 equaling Saturday. The parameter is allowed only if the optional input port exists. If this parameter is omitted, the day of the week component is not updated.

Properties

hourAttribute

he name of the input attribute that updates the hour component. Valid values are 0 to 23, inclusive. The parameter is allowed only if the optional input port exists. If this parameter is omitted, the hour component is not updated.

Properties

minuteAttribute

The name of the input attribute that updates the minute component. Valid values are 0 to 59, inclusive. This parameter is allowed only if the optional input port exists. If this parameter is omitted, the minute component is not updated.

Properties

tensecAttribute

The name of the input attribute that updates the ten seconds interval component. Valid values are 0 to 5. For example, a value of 1 equals 10 seconds, and a value of 5 equals 50 seconds. This parameter is allowed only if the optional input port exists. If this parameter is omitted, the ten seconds interval component is not updated.

Properties

initDelay

The number of seconds that the operator waits before starting the scheduler logic. If this parameter is omitted, the ScheduledBeacon starts the scheduler logic immediately.

Properties

initialTrigger

Specifies whether to send a tuple after the initial delay. The default value is false, meaning that a tuple is not sent.

Properties

ignoreInvalidSchedule

Specifies how to treat incorrectly formatted tuples. When this parameter is set to false, incorrectly formatted tuples produce a runtime error and terminate the operator. When this parameter is set to true, incorrectly formatted tuples produce a runtime log entry, and the operator tries to skip to the next tuple and continue. The old schedule remains active. The default value is false.

Properties

Code Templates

ScheduledBeacon
stream<uint64 count> ${OutputStream} as O = ScheduledBeacon()
{
	param
		initDelay: ${initialDelay};
		month: "${month}";
		mday: "${dayOfMonth}";
		wday: "${dayOfWeek}";
		hour: "${hour}";
		minute: "${minute}";
		tensec: "${tensec}";${cursor}
	output O: count = IterationCount();
}

ScheduledBeacon with variable schedule
stream<uint64 count> ${OutputStream} as O = ScheduledBeacon(${ControlStream} as I)
{
	param
		initDelay: ${initialDelay};
		monthAttribute: ${month};
		mdayAttribute: ${dayOfMonth};
		wdayAttribute: ${dayOfWeek};
		hourAttribute: ${hour};
		minuteAttribute: ${minute};
		tensecAttribute: ${tensec};${cursor}
	output O: count = IterationCount();
}

Metrics

nInvalidSchedules - Counter

The number of invalid received schedules (because of conversion errors).