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 the "nth day of week in a month", which allows for yet undetermined dates in 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">

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

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 fd:fixed_duration_as 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 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.
- You will find there's a blueprint attribute at the interval element; it tells the scheduling engine how to treat the list of time points (onset elements).
  1. 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. 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. 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".
- 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 regard to a 'holiday' schedule some days must be observed during the week, like "Independence Day". Those holidays may fall on a weekend, so it doesn't make sense to repeat them indefinitely, but fix them to a specific year.
- Some holidays may occur every 4 years, which requires a fixed start year.

	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.

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