Public Holiday Schedules

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 a "week day ordinal", which allows for yet undetermined dates in a month like the "3rd Monday" or a year like the "3rd Monday of January".

Concepts and properties of a schedule

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" fd:calendar_date_adjustment_rule="us_federal_holiday_observance">

        <!-- 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>

There can be one or multiple schedules.
A schedule is defined by time points, denoting either restart, execution duration (uptime) or halt of execution (downtime), and possibly a rule to adjust a date on which the public holiday is actually observed.
- 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 defined by the attribute fd:fixed_duration_as="downtime" (→ "Halt") or fd:fixed_duration_as="uptime" (or its absence) (→ "Duration").
  
  Note
  
  The fd:fixed_duration_as is a foreign attribute. It's up to the programmer to handle it.
- The timepoint generator recognizes rules for adjusting a fixed date when it is actually observed, two of which are built in:
  1. fd:calendar_date_adjustment_rule="us_federal_holiday_observance" → When a legal public holiday falls on a Saturday, it is usually observed on the preceding Friday. When the holiday falls on a Sunday, it is usually observed on the following Monday.
  2. fd:calendar_date_adjustment_rule="us_inauguration_day_observance" → When Inauguration Day falls on a Sunday, it is usually observed on the following Monday.
  Note
  
  The fd:calendar_date_adjustment_rule is a foreign attribute. It's up to the programmer to handle it.
Time points recur in intervals.
- 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 public holiday schedule, consisting of certain days 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.
- You will find there's a blueprint attribute at the interval element; it tells the timepoint generator how to treat the list of time points (onset elements).
  1. blueprint="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.
  2. blueprint="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.
  3. blueprint="fixed_subrange_duration" tells it to expect the onsets 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".
- To express restarts, only a single onset is needed.
- To express uptime or downtime, the onsets come in pairs, defining begin and completion (exclusive).
  1. For an uptime (duration) schedule the first onset element marks the start of uptime (the process will be started), the second onset element marks the end of uptime (the process will be terminated).
  2. Conversely, for a downtime (halt) schedule the first onset element marks the start of downtime (the process will be terminated), the second onset element marks the end of downtime (the process will be started).
The activity_boundary fixes a schedule to a certain period.

This can be useful for various reasons:
- In relation to a calendar-based schedule, there may be culturally or politically motivated observance rules, such as "Independence Day" in the USA. The time generator already recognizes some rules, but there may be rules that are not yet covered. In this case, if you cannot provide custom functions, it may be useful to set the schedule to a specific year.
- Some holidays may occur every 4 years, which requires a fixed start year.
- A schedule should simply end.

	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).

Difference and usefulness of "Halt" and "Duration"

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.

Usefulness of "date adjustment rules"

Remember: The timepoint generator knows nothing about the culturally or politically motivated observance of public holidays. However, it can be configured to adjust the date as needed. This can be achieved by selecting a function from the set of forwarded date adjustment functions via the corresponding rule name. If the built-in rules are not sufficient, you can create your own C++ adjustment functions.

	Note
	The `fd:fixed_duration_as` is a foreign attribute. It's up to the programmer to handle it.

	Note
	The `fd:calendar_date_adjustment_rule` is a foreign attribute. It's up to the programmer to handle it.