Scheduling executions of the start method of a scheduled service instance (specified by the exec attribute of the scheduled_method element) always requires the values of the interval and frequency attributes of the scheduled_method element. The frequency attribute has a default value of 1. The value of the interval attribute must be explicitly set. Other specified attributes of the scheduled_method element or properties of property groups of type schedule are also used, and the next_run value might be used.
If the value of frequency is 1, the start method of a scheduled service instance is initially invoked at a random time within the smallest specified constraint. Subsequent invocations occur within the same unit of the next shorter constraint in the next execution interval. For example, if the interval is week and no other scheduling constraints are specified, the start method will initially be invoked at a random time during the week. Subsequent invocations will occur within the same day in future weeks so that the start method will not be invoked on two consecutive days, for example. Similarly, if the interval is week, and day and hour are also specified, the start method will initially be invoked at a random time during the specified hour on the specified day; subsequent invocations will occur within the same minute during the specified hour and day in future weeks.
If the value of frequency is greater than 1, scheduling constraints that are the same length of time or longer than the interval value are used to set the time of the initial invocation. All constraints from year down to the same length of time as the interval value must be specified. For example, if interval is week, values must be specified for year and week_of_year.
If interval is week, frequency is 2, year is 2014, and week_of_year is any even number from 2 through 52, then the start method will be invoked every even-numbered week. If week_of_year is any odd number from 1 through 53, then the start method will be invoked every odd-numbered week. Because the year 2014 has already passed, the value of the week_of_year attribute in this example does not indicate the particular week when the start method will initially be invoked, but only whether it will be invoked in the next even week or the next odd week. Subsequent invocations will occur every two weeks, so that after a year that has 53 weeks, such as 2015, the start method that was initially invoked in an even-numbered week will be invoked in odd-numbered weeks.
If interval is week, frequency is 4, year is 2014, and week_of_year is 1, the start method will be invoked in weeks 1, 5, 9, and so forth in 2015. Because 2015 has 53 weeks, the start method will be invoked in week 53, and in 2016 the start method will be invoked in weeks 4, 8, 12, and so forth.
Sometimes one set of scheduling constraints is not enough to define the schedule. A scheduled service can have multiple property groups of type schedule. The periodic restarter combines the values of each property of each property group of type schedule to schedule invocations of the start method of the scheduled service instance.
Just as a scheduled service should have only as many scheduling constraints as necessary to define the schedule, a scheduled service should have only as many schedule property groups as necessary to define the required schedule for the task.
Example 4 Invoking Every Twelve HoursIn this example, the start method is invoked at 06:00 and 18:00 every day. The value of the hour attribute could be either 6 or 18.
<?xml version='1.0'?>
<!DOCTYPE service_bundle
SYSTEM '/usr/share/lib/xml/dtd/service_bundle.dtd.1'>
<service_bundle type='manifest' name='site/sample-periodic-svc'>
<service type='service' version='1' name='site/sample-periodic-svc'>
<instance name='default' enabled='false'>
<scheduled_method
interval='hour'
frequency='12'
hour='6'
minute='0'
exec='/usr/bin/scheduled_service_method'
timeout_seconds='0'>
<method_context>
<method_credential user='root' group='root' />
</method_context>
</scheduled_method>
</instance>
</service>
</service_bundle>
Example 5 Invoking Daily at 03:00 and 23:00
In this example, an additional schedule property group is specified to invoke the start method at 03:00 and 23:00 every day.
<?xml version='1.0'?>
<!DOCTYPE service_bundle
SYSTEM '/usr/share/lib/xml/dtd/service_bundle.dtd.1'>
<service_bundle type='manifest' name='site/sample-periodic-svc'>
<service type='service' version='1' name='site/sample-periodic-svc'>
<instance name='default' enabled='false'>
<scheduled_method
interval='day'
hour='3'
minute='0'
exec='/usr/bin/scheduled_service_method'
timeout_seconds='0'>
<method_context>
<method_credential user='root' group='root' />
</method_context>
</scheduled_method>
<property_group name='run2' type='schedule'>
<propval name='interval' type='astring' value='day' />
<propval name='hour' type='integer' value='23' />
<propval name='minute' type='integer' value='0' />
</property_group>
</instance>
</service>
</service_bundle>
Example 6 Invoking at 03:00 and 23:00 on Tuesday and Thursday
To invoke the start method at 03:00 and 23:00 every Tuesday and Thursday requires three additional schedule property groups, as shown in this example.
<?xml version='1.0'?>
<!DOCTYPE service_bundle
SYSTEM '/usr/share/lib/xml/dtd/service_bundle.dtd.1'>
<service_bundle type='manifest' name='site/sample-periodic-svc'>
<service type='service' version='1' name='site/sample-periodic-svc'>
<instance name='default' enabled='false'>
<scheduled_method
interval='week'
day='3'
hour='3'
minute='0'
exec='/usr/bin/scheduled_service_method'
timeout_seconds='0'>
<method_context>
<method_credential user='root' group='root' />
</method_context>
</scheduled_method>
<property_group name='run2' type='schedule'>
<propval name='interval' type='astring' value='week' />
<propval name='day' type='astring' value='3' />
<propval name='hour' type='integer' value='23' />
<propval name='minute' type='integer' value='0' />
</property_group>
<property_group name='run3' type='schedule'>
<propval name='interval' type='astring' value='week' />
<propval name='day' type='astring' value='5' />
<propval name='hour' type='integer' value='3' />
<propval name='minute' type='integer' value='0' />
</property_group>
<property_group name='run4' type='schedule'>
<propval name='interval' type=astring'' value='week' />
<propval name='day' type='astring' value='5' />
<propval name='hour' type='integer' value='23' />
<propval name='minute' type='integer' value='0' />
</property_group>
</instance>
</service>
</service_bundle>
If the service is already imported, you can specify these additional property groups by using a site profile or by using the svccfg subcommands addpg and setprop.
If scheduling constraints are specified such that multiple start method invocation times are possible in a single interval, the start method will be invoked at the earliest time that matches all constraints. An example of multiple possible invocation times in a single interval is when switching from daylight saving time to standard time, when times between 01:00 and 02:00 occur twice.
The recover property can modify the time the scheduled instance method runs when a scheduled instance emerges from system downtime.
If the value of the recover property is true, the periodic restarter invokes the start method for the scheduled service instance as soon as possible as the instance emerges from system downtime. Subsequent invocations occur according to the interval and frequency values and any other specified constraints.
If the value of the recover property is false, the periodic restarter invokes the start method for the scheduled service instance at the time specified by the next_run property. If the value of the next_run property is in the past, future start method invocations occur according to the interval and frequency values and any other specified constraints. The next_run property is described in Last and Next Start Method Invocations.
The periodic restarter service (svc:/system/svc/periodic-restarter) automatically attempts to restart if it terminates. When the periodic restarter service restarts after failure, the start method of each scheduled instance is invoked at the time specified by the next_run property. If the value of the next_run property is in the past, future start method invocations occur according to the interval and frequency values and any other specified constraints. The next_run property is described in Last and Next Start Method Invocations.
If a scheduled service instance is restarted, the start method for the instance is invoked according to the interval and frequency values and any other specified constraints.
The start method should perform a task and then terminate within the period specified by the interval and frequency properties. If a contracted process still exists when the periodic restarter attempts to invoke the start method in the next scheduled interval, then the invocation for that period is skipped and the periodic restarter attempts to invoke the start method again at the following period.
If the start method runs longer than the number of seconds specified by the timeout_seconds value, all processes in the contract are terminated and the invocation is a non-fatal fault. The first time the start method terminates in any non-fatal fault, the instance is placed into the degraded state and start method invocations continue as scheduled according to the interval and frequency values and any other specified constraints. If one of the following two invocations succeeds, the instance is placed back into the online state.
After three successive non-fatal faults of the start method, the instance is moved from the degraded state to the maintenance state. On the first fatal fault of the start method, the service is placed into the maintenance state. See Repairing an Instance That Is Degraded, Offline, or in Maintenance in Managing System Services in Oracle Solaris 11.3.