Schedule¶
A Schedule is a data type used to define when certain actions or data collections should occur. A Schedule can describe tasks to be executed periodically, at a specific time, or both. Further, you can define during which time frime during a day a Schedule should be active etc.
Schedules in Modules
Modules typically use Schedules as a property, and then register functions based on that Schedule, allowing the user to precisely control when certain actions or data collections should occur. See below.
Structure¶
A Schedule consists of two main components:
- Periodic schedules (
periodic): A list of periodic Schedules, i.e., periods or frequencies at which rate to execute. - Exact time schedules (
timed): A list of exact time Schedules, i.e., specific times to execute.
An empty Schedule looks as follows:
Periodic Schedules¶
Periodic schedules define recurring events based on a specified time interval. They can be set using different time units such as minutes, seconds, or frequency in Hertz. Each periodic schedule is an object within the periodic array.
A periodic schedule can have the following properties:
period_milliseconds: Defines the interval in milliseconds.period_seconds: Defines the interval in seconds.period_minutes: Defines the interval in minutes.period_hours: Defines the interval in hours.period_days: Defines the interval in days.frequency_Hz: Defines the frequency in Hertz (events per second).frequency_kHz: Defines the frequency in kHz (events per millisecond).frequency_MHz: Defines the frequency in MHz (events per microsecond).only_active_between_time_frame: Optional. Specifies a time frame during which the schedule is active (e.g., between 12:00 and 18:00).first_execution_time_of_day: Optional. Specifies the first execution time of the day. E.g., if the schedule is set to execute every 5 minutes, the first execution time of the day could be at 12:00.
Example:
Example for Periodic Schedules
The following shows an example for a Schedule which will execute every 5 minutes.
You can, of course, also combine multiple periodic schedules. For example, the following Schedule will execute every 5 minutes and every 10 seconds.
You can also define time windows during which a periodic schedule is active. For example, the following allows you to define a measurement period of 5 minutes, which is only active between 22:00 at night to 08:30 in the morning.
Exact Time Schedules¶
Exact time schedules define specific events that occur at an exact specified time. A timed schedule can have the following properties:
time_of_day: Defines the time of day when the schedule should be executed.repeat_every_n_days: Optional. Specifies the interval in days for the schedule to repeat (e.g., every 2 days).
Example:
Example for Exact Time Schedules
The following shows an example for a Schedule which will executes at 12:30 every two days.
"schedule": {
"periodic": [],
"timed": [{
"time_of_day": {
"hour": 12,
"minute": 30,
"repeat_every_n_days": 2
}
}]
}
You can, of course, also combine multiple timed schedules. For example, the following Schedule will execute at 12:30 every two days and at 15:00 every three days.
Combined Schedules¶
You can combine an arbitrary number of periodic and timed schedules. The following example shows a Schedule which will execute every 5 minutes, 50 times per second, every 10 seconds between 12:00 and 18:00, at 12:30 every day, and at 15:00 every two days.
Example:
Example Schedule
The following shows an example Schedule with 5 entries:
- It will execute every 5 minutes
- It will execute 50 times per second, i.e., every 20 ms
- It will execute every 10 seconds between 12:00 and 18:00
- It will execute at 12:30 every day
- It will execute at 15:00 every two days
"schedule": {
"periodic": [
{
"period_minutes": 5
},
{
"frequency_Hz" : 50
},
{
"period_seconds": 10,
"only_active_betwen_time_frame" : {
"start_time_of_day": {
"hour": 12,
"minute": 00,
},
"stop_time_of_day": {
"hour": 18,
"minute": 00
},
}
}
],
"timed": [
{
"time_of_day": {
"hour": 12,
"minute": 30,
"repeat_every_n_days": 1
}
},
{
"time_of_day": {
"hour": 15,
"minute": 00,
"repeat_every_n_days": 2
}
}
]
}
Using Schedules in Modules¶
Schedules provide a very convenient way to define when certain actions or data collections of a CLAID Module should occur. From a Module, you can specify a Schedule as property of the Module, and then simply register functions based on that Schedule. This only requires two lines of code:
Using a Schedule in a Module
Consider the following configuration file for a Module of type MyModule:
{
"hosts": [{
"hostname": "MyHost",
"modules": [{
"id": "SomeModule",
"type": "MyModule",
"properties": {
"mySchedule": {
"periodic": [{
"period_minutes": 5
}],
}
}
}]
}]
}
You can define the class MyModule as follows, to register functions based on a Schedule.
class MyModule extends Module
{
// Register a function to be executed based on the Schedule
@Override
public void initialize(Properties properties)
{
Schedule schedule = properties.getObjectProperty("mySchedule");
registerFunctionBasedOnSchedule("MyScheduledFunction", schedule, () -> myFunction());
}
}
private void myFunction()
{
// This function will be executed based on the Schedule.
}
// Register a function to be executed based on the Schedule
class MyModule : public Module
{
public:
void initialize(Properties properties)
{
Schedule schedule = properties.getObjectProperty("mySchedule");
registerFunctionBasedOnSchedule("MyScheduledFunction", schedule, &MyModule::myFunction, this);
}
void myFunction() {
// This function will be executed based on the Schedule.
}
};
class MyModule(Module):
# Register a function to be executed based on the Schedule
def initialize(self, properties):
self.schedule = properties.get_object_property("mySchedule")
self.register_function_based_on_schedule("my_scheduled_function", schedule, self.my_function)
def my_function(self):
# This function will be executed based on the Schedule.