One of the finest things you can do with the timepoint generator is to schedule actions for annual events on calendar dates.
Goal
For this example we will create a schedule observing the US Federal Holidays, which halts a program during the holiday until the next morning (from 4AM to 4AM), plus a daily restart schedule.
More detailed information about the federal US holidays can be found on https://www.redcort.com/us-federal-bank-holidays/.
synkronize
features "Halt" schedules additionally
to "Duration" schedules, plus scheduling on the "nth day of
week in a month", which allows for yet undetermined dates in a year
like the "3rd Monday of January".
Let's take a look at a single 'Halt Execution' schedule represented in XML:
<!-- 1. --> <fds:schedules xmlns:fds="http://xml.firedaemon.com/scheduling/v3" xmlns:fd="http://xml.firedaemon.com"> <!-- 2. --> <schedule name="New Year's Day" fd:fixed_duration_as="downtime"> <!-- 3. --> <interval xsi:type="fds:attributive_interval" granularity="year_interval" length="1" blueprint="fixed_subrange_duration"> <!-- 4. --> <onset name="New Year's Day" minute="0" hour="4" monthday="0" month="0"/> <onset minute="0" hour="4" monthday="0" month="0"/> </interval> <!-- 5. --> <activity_boundary/> </schedule> </fds:schedules>
A schedule is defined by time points, denoting either restart, execution duration (uptime) or halt of execution (downtime).
A schedule has a name, which is optional, but highly recommended, as it is used for display in various places, for identity and makes things much more understandable.
The difference between a "Duration" and a "Halt"
schedule is simply the attribute fd:fixed_duration_as="downtime"
(→ "Halt") or fd:fixed_duration_as="uptime"
(or its absence) (→ "Duration").
Note | |
---|---|
The |
The scheduling model is designed for different intervals: by the second, by the minute, hourly, daily, weekly, monthly, yearly, by the leapyear.
Since the goal is to define a holiday schedule, consisting of
certain periods in a year, a 'yearly' interval schedule is what
we need in this example. The interval's resolution is called
"granularity", which is set to granularity="year_interval"
for a yearly repeating schedule.
evenly_clocked
lets you freely specify the day of year for each time point
in an interval, however the time of (i.e. hour, minute,
second) of all time points will be equalized to the first
time point. This rule also applies to the 'duration' blueprint
values.
fixed_duration
tells it to expect onsets in pairs and consider them as
begin and completion of two time points when the application
should execute or halt.
fixed_subrange_duration
tells it to expect theonsets in pairs and consider them
as begin and completion of a day when the application should
execute or halt.
A time point is called onset, in order to express that some action is associated with the time point (which is similar to music theory).
An onset's attributes (second, minute, ...) configure when the action should happen, counted from the beginning of the interval (i.e. the beginning of year for a yearly schedule).
This simply means that all offset values are 0-based; i.e. the 5th
hour (4 o'clock) is expressed as hour="4"
,
the 11th month (November) is expressed as month="10"
.
The activity_boundary
fixes a schedule to a certain period.
This can be useful for various reasons:
Note | |
---|---|
All 'until time point' values (i.e. the second onset element of onset/completion pairs) [found at activity boundary, completion time point, end of range] denote an exclusive time point (this makes sense when doing calculations internally, plus it let's you specify periods covering the whole interval easily). |
Remember: The timepoint generator knows nothing about actions, but only timepoints marking the onset of some action or pairs of timepoints marking onset and completion for an action. In this sense, a "fixed duration" schedule is nothing more than pairs of timepoints marking the begin and completion of whatever you find applicable for your program.
However, differentiating "Halt" from "Duration" is
useful when you mix "Duration" (start/stop) and "Halt"
(stop/start) schedules and you want to treat both in a uniform way. The
timepoint generator has a mode setting that flips stop/start timepoint
pairs into start/stop pairs, hence effectively turning the schedule into
a regular "Duration" schedule. See fd::timepiece_settings::fixed_duration_as
.