Scheduler

Data Structures
struct	_scheduler_item
	Structure containing a schedule item. More...
struct	_scheduler
	Structure containing a scheduler. More...

Typedefs
typedef struct _scheduler_item	amxp_scheduler_item_t
	Structure containing a schedule item. More...
typedef struct _scheduler	amxp_scheduler_t
	Structure containing a scheduler. More...

Functions
int	amxp_scheduler_new (amxp_scheduler_t **scheduler)
	Allocates a amxp_scheduler_t structures and initializes to an empty scheduler. More...
void	amxp_scheduler_delete (amxp_scheduler_t **scheduler)
	Frees the previously allocated amxp_scheduler_t structure. More...
int	amxp_scheduler_init (amxp_scheduler_t *scheduler)
	Initializes a amxp_scheduler_t to an empty scheduler. More...
void	amxp_scheduler_clean (amxp_scheduler_t *scheduler)
	Cleans the scheduler. More...
int	amxp_scheduler_enable (amxp_scheduler_t *scheduler, bool enable)
	Enables or disable the scheduler. More...
int	amxp_scheduler_use_local_time (amxp_scheduler_t *scheduler, bool use_local_time)
	Use local time or UTC time in calculation for next trigger times. More...
int	amxp_scheduler_update (amxp_scheduler_t *scheduler)
	Forces recalculation of the schedule items' next occurrence time. More...
int	amxp_scheduler_connect (amxp_scheduler_t *scheduler, const char *id, amxp_slot_fn_t fn, void *priv)
	Connects a callback function to the scheduler. More...
int	amxp_scheduler_disconnect (amxp_scheduler_t *scheduler, const char *id, amxp_slot_fn_t fn)
	Disconnects a callback function from the scheduler. More...
int	amxp_scheduler_set_cron_item (amxp_scheduler_t *scheduler, const char *id, const char *cron_expr, uint32_t duration)
	Adds a schedule item or updates a schedule item using a cron expression. More...
int	amxp_scheduler_set_cron_begin_end_item (amxp_scheduler_t *scheduler, const char *id, const char *cron_begin, const char *cron_end)
	Adds a schedule item or updates a schedule item using a cron expressions. More...
int	amxp_scheduler_set_weekly_item (amxp_scheduler_t *scheduler, const char *id, const char *time, const char *days_of_week, uint32_t duration)
	Adds a schedule item or updates a schedule item using a time and list of week days. More...
int	amxp_scheduler_set_weekly_begin_end_item (amxp_scheduler_t *scheduler, const char *id, const char *start_time, const char *end_time, const char *days_of_week)
	Adds a schedule item or updates a schedule item using a start time, end time and list of week days. More...
int	amxp_scheduler_remove_item (amxp_scheduler_t *scheduler, const char *id)
	Removes a schedule item from the scheduler. More...
int	amxp_scheduler_enable_item (amxp_scheduler_t *scheduler, const char *id, bool enable)
	Enables or disable a schedule item. More...
amxp_signal_mngr_t *	amxp_scheduler_get_sigmngr (amxp_scheduler_t *scheduler)
	Gets the signal manager of a scheduler. More...

Detailed Description

Ambiorix Scheduler.

A scheduler takes schedule items, which can be defined using a cron expression. A schedule item triggers at some point in time, when a schedule is triggered the scheduler will emit the signal "trigger:ID".

Each schedule item has an identifier (which must be unique within the allocated scheduler), this identifier is passed as data in the signal and is also used in the name of the signal.

A schedule item can have a duration (in seconds). When the schedule item triggers and has a duration different from 0, the scheduler will emit the signal "start:ID" and when the duration expires the scheduler will emit the signal "stop:ID".

Typedef Documentation

amxp_scheduler_item_t

typedef struct _scheduler_item amxp_scheduler_item_t

Structure containing a schedule item.

This structure defines a schedule item. A schedule item defines points in time and can optionally have duration. The points in time are defined using a cron expression. The duration can either be a fixed time in seconds or another point in time defined using a second cron expression.

A schedule item can be enabled or disabled at any moment.

A schedule item has a unique identifier, which can be any string, and must be unique within a scheduler. The schedule item identifier is used in the signal names.

To activate a schedule item it must be added to a scheduler. Whenever the defined point in time is readched the scheduler will emit or trigger a signal (event).

Multiple callback functions (slots) can be added to the scheduler, either on all schedule items or on a specific item.

amxp_scheduler_t

typedef struct _scheduler amxp_scheduler_t

Structure containing a scheduler.

A scheduler can contain multiple schedule items (amxp_scheduler_item_t). Each time an item is added (using amxp_scheduler_set_cron_item, amxp_scheduler_set_weekly_item, amxp_scheduler_set_cron_begin_end_item, amxp_scheduler_set_weekly_begin_end_item), the list of items is updated and sorted again. The first item in the list is the item the will be triggered first.

A scheduler always works on the current time (UTC or local time). So make sure that time synchronization has happend before using a scheduler.

When NTP synchronization didn't happen yet, it is recommened to disable the scheduler and enable it again when time synchronization has happened.

A scheduler can be enabled or disabled using amxp_scheduler_enable.

A scheduler contains a signal manager. This signal manager will be used to emit the signals "trigger:ID", "start:ID", "stop:ID". (Here the ID is the schedule item identifier)

When these signals are emitted, the signal data will contain the schedule item identifier and the reason (trigger, start, stop). When the "start" signal is emitted, the signal data will also contain the duration in seconds before the "stop" signal is emitted.

Callback functions (slots) can be added using amxp_scheduler_connect or by using one of the amxp_slot_connect functions, and removed again using one of the amxp_slot_disconnect functions.

Function Documentation

amxp_scheduler_clean()

void amxp_scheduler_clean

(

amxp_scheduler_t *

scheduler

)

Cleans the scheduler.

All schedule items will be removed, all running timers will be stopped and deleted.

When a schedule item with duration was started, a "stop" signal will be emitted before the schedule item is deleted.

Before using the scheduler again, make sure it is initialized again using amxp_scheduler_init.

Parameters

scheduler

pointer to an amxp_cron_expr_t structure

Definition at line 364 of file amxp_scheduler.c.

                                                       {
    when_null(scheduler, exit);
    amxp_sigmngr_clean(&scheduler->sigmngr);
    amxp_timer_delete(&scheduler->timer);
    amxc_llist_for_each(it, &scheduler->ordered_items) {
        amxp_scheduler_item_t* item = amxc_container_of(it, amxp_scheduler_item_t, lit);
        if((item->timer != NULL) && (item->timer->state == amxp_timer_running)) {
            amxp_scheduler_emit(scheduler, item, "stop", 0, true);
        }
    }
    amxc_llist_clean(&scheduler->ordered_items, amxp_schedule_item_delete);
    amxc_htable_clean(&scheduler->items, NULL); // items are freed when cleaning ordered list.
 
exit:
    return;
}

amxp_scheduler_connect()

int amxp_scheduler_connect	(	amxp_scheduler_t *	scheduler,
		const char *	id,
		amxp_slot_fn_t	fn,
		void *	priv
	)

Connects a callback function to the scheduler.

A callback functions can be added to a scheduler for a specific schedule item identifier or for all currently known schedule items.

Alternativly the amxp_slot_connection functions can be used to connect to the scheduler signals.

Multiple callback functions can be added to the scheduler.

The possible scheduler signals are:

• trigger:ID - only for schedule items without a duration
• start:ID - only for schedule items with a duration, will be followed by a stop signal
• stop:ID - only for schedule items with a duration, is always preceded with a start signal

The ID in above signal names is replaced by the identifier of the scheduler item.

A pointer to private data can be passed as well. This pointer is passed to the callback function. The scheduler itself will not use this private data and will not take ownership of the pointer. If memory was allocated it is up to the caller to manage the allocated memory.

Parameters

scheduler	pointer to an amxp_scheduler_t structure
id	(optional) the identifier for which the callback funcion (slot) must be called
fn	the pointer to the callback function
priv	private data, will be passed to the callback function

Returns

When successfull, this functions returns 0.

Definition at line 448 of file amxp_scheduler.c.

                                       {
 
    int rv = -1;
    amxc_string_t signal;
    amxc_htable_it_t* hit = NULL;
    amxp_scheduler_item_t* item = NULL;
 
    amxc_string_init(&signal, 0);
    when_null(scheduler, exit);
 
    if((id == NULL) || (*id == 0)) {
        // connect to all signals
        rv = amxp_slot_connect(&scheduler->sigmngr, "*", NULL, fn, priv);
        goto exit;
    }
 
    hit = amxc_htable_get(&scheduler->items, id);
    when_null(hit, exit);
    item = amxc_container_of(hit, amxp_scheduler_item_t, hit);
    when_null(item, exit);
 
    amxc_string_setf(&signal, "start:%s", id);
    rv = amxp_slot_connect(&scheduler->sigmngr, amxc_string_get(&signal, 0), NULL, fn, priv);
    when_failed(rv, exit);
    amxc_string_setf(&signal, "stop:%s", id);
    rv = amxp_slot_connect(&scheduler->sigmngr, amxc_string_get(&signal, 0), NULL, fn, priv);
    when_failed(rv, exit);
    amxc_string_setf(&signal, "trigger:%s", id);
    rv = amxp_slot_connect(&scheduler->sigmngr, amxc_string_get(&signal, 0), NULL, fn, priv);
 
exit:
    amxc_string_clean(&signal);
    return rv;
}

amxp_scheduler_delete()

void amxp_scheduler_delete

(

amxp_scheduler_t **

scheduler

)

Frees the previously allocated amxp_scheduler_t structure.

Frees the allocated memory and sets the pointer to NULL.

All schedule items will be deleted as well, all running timers will be stopped and deleted.

When a schedule item with duration was started, a "stop" signal will be emitted before the schedule item is deleted.

Note

Only call this function for amxp_scheduler_t structures that are allocated on the heap using amxp_scheduler_new.

Parameters

scheduler

pointer to a pointer that points to the allocated amxp_scheduler_t structure

Definition at line 332 of file amxp_scheduler.c.

                                                         {
    when_null(scheduler, exit);
    when_null(*scheduler, exit);
 
    amxp_scheduler_clean(*scheduler);
    free(*scheduler);
    *scheduler = NULL;
 
exit:
    return;
}

amxp_scheduler_disconnect()

int amxp_scheduler_disconnect	(	amxp_scheduler_t *	scheduler,
		const char *	id,
		amxp_slot_fn_t	fn
	)

Disconnects a callback function from the scheduler.

A previously added callback functions can be removed from a scheduler for a specific schedule item identifier or for all currently known schedule items.

Alternativly the amxp_slot_disconnect functions can be used to disconnect from the scheduler signals.

If a NULL pointer is used as the id the function will be removed from all signals from the scheduler.

Parameters

scheduler	pointer to an amxp_scheduler_t structure
id	(optional) the identifier for which the callback funcion (slot) must be removed
fn	the pointer to the callback function

Returns

When successfull, this functions returns 0.

Definition at line 486 of file amxp_scheduler.c.

                                                 {
 
    int rv = -1;
    amxc_string_t signal;
    amxc_htable_it_t* hit = NULL;
    amxp_scheduler_item_t* item = NULL;
 
    amxc_string_init(&signal, 0);
    when_null(scheduler, exit);
 
    if((id == NULL) || (*id == 0)) {
        // connect to all signals
        amxp_slot_disconnect_all(fn);
        rv = 0;
        goto exit;
    }
 
    hit = amxc_htable_get(&scheduler->items, id);
    when_null(hit, exit);
    item = amxc_container_of(hit, amxp_scheduler_item_t, hit);
    when_null(item, exit);
 
    amxc_string_setf(&signal, "start:%s", id);
    rv = amxp_slot_disconnect(&scheduler->sigmngr, amxc_string_get(&signal, 0), fn);
    when_failed(rv, exit);
    amxc_string_setf(&signal, "stop:%s", id);
    rv = amxp_slot_disconnect(&scheduler->sigmngr, amxc_string_get(&signal, 0), fn);
    when_failed(rv, exit);
    amxc_string_setf(&signal, "trigger:%s", id);
    rv = amxp_slot_disconnect(&scheduler->sigmngr, amxc_string_get(&signal, 0), fn);
 
exit:
    amxc_string_clean(&signal);
    return rv;
}

amxp_scheduler_enable()

int amxp_scheduler_enable	(	amxp_scheduler_t *	scheduler,
		bool	enable
	)

Enables or disable the scheduler.

When enabling a previously disabled scheduler, a recalculation is done of all schedule items and a timer is started that will expires when the first schedule triggers.

Enabling an empty scheduler (that is a scheduler without any schedule items), will have no effect.

When disabling a scheduler no signals will be emitted anymore for that scheduler, except the "stop" signals. This signal will be emitted for schedules that have a duration and were already started.

Parameters

scheduler	pointer to an amxp_scheduler_t structure
enable	when set to true, the scheduler will be enable.

Returns

When successfull, this functions returns 0.

Definition at line 381 of file amxp_scheduler.c.

                                                                    {
    int rv = -1;
 
    when_null(scheduler, exit);
    when_true_status(scheduler->sigmngr.enabled == enable, exit, rv = 0);
 
    amxp_sigmngr_enable(&scheduler->sigmngr, enable);
    if(enable) {
        amxp_scheduler_update(scheduler);
        amxp_scheduler_reset_timer(scheduler);
    }
    if(!enable) {
        amxp_scheduler_update(scheduler);
        amxp_timer_stop(scheduler->timer);
    }
 
    rv = 0;
 
exit:
    return rv;
}

amxp_scheduler_enable_item()

int amxp_scheduler_enable_item	(	amxp_scheduler_t *	scheduler,
		const char *	id,
		bool	enable
	)

Enables or disable a schedule item.

When a schedule item is added to the scheduler, it will be enabled by default.

By disabling the schedule item, the scheduler will still take the item into account for time calculation, but will not emit signals for it.

Parameters

scheduler	pointer to an amxp_scheduler_t structure
id	the identifier for schedule item
enable	false to disable to schedule item, true to enable it.

Returns

When successfull, this functions returns 0.

Definition at line 680 of file amxp_scheduler.c.

                                            {
    int rv = -1;
    amxc_htable_it_t* hit = NULL;
    amxp_scheduler_item_t* item = NULL;
 
    when_null(scheduler, exit);
    when_str_empty(id, exit);
 
    hit = amxc_htable_get(&scheduler->items, id);
    when_null(hit, exit);
    item = amxc_container_of(hit, amxp_scheduler_item_t, hit);
    when_true_status(enable == item->enabled, exit, rv = 0);
 
    item->enabled = enable;
    if(!enable) {
        if((item->timer != NULL) && (item->timer->state == amxp_timer_running)) {
            amxp_scheduler_emit(scheduler, item, "stop", 0, false);
            amxp_timer_delete(&item->timer);
        }
    } else {
        amxp_scheduler_check_item(scheduler, item);
        amxp_scheduler_reset_timer(scheduler);
    }
 
    rv = 0;
 
exit:
    return rv;
}

amxp_scheduler_get_sigmngr()

amxp_signal_mngr_t* amxp_scheduler_get_sigmngr

(

amxp_scheduler_t *

scheduler

)

Gets the signal manager of a scheduler.

Returns the signal manager of the scheduler. This can be used to connect or disconnect slots (callback functions)

Parameters

scheduler

pointer to an amxp_scheduler_t structure

Returns

Pointer to the signal manager of the scheduler or NULL.

Definition at line 712 of file amxp_scheduler.c.

                                                                            {
    amxp_signal_mngr_t* sigmngr = NULL;
    when_null(scheduler, exit);
 
    sigmngr = &scheduler->sigmngr;
 
exit:
    return sigmngr;
}

amxp_scheduler_init()

int amxp_scheduler_init

(

amxp_scheduler_t *

scheduler

)

Initializes a amxp_scheduler_t to an empty scheduler.

This function initializes it to an empty scheduler.

An empty scheduler will be inactive (no timer is started) until the first schedule item is added.

By default the scheduler will be enabled. When adding schedule items they will be taken into account immediatly. If more control is needed, first disable the scheduler by calling amxp_scheduler_enable.

By default the scheduler will use UTC time, if all calculations needs to be done on local time call the function amxp_scheduler_use_local_time.

Use amxp_scheduler_set_cron_item, amxp_scheduler_set_cron_begin_end_item, amxp_scheduler_set_weekly_item or amxp_scheduler_set_weekly_begin_end_item to add schedule items.

Note

When the scheduler is not used any more, the function amxp_scheduler_clean must be called. It will do the scheduler clean-up (removes all schedule items and timers).

Parameters

scheduler

pointer to a amxp_schedule_t structure

Returns

When initialization is successfull, this functions returns 0.

Definition at line 344 of file amxp_scheduler.c.

                                                     {
    int rv = -1;
 
    when_null(scheduler, exit);
 
    amxp_sigmngr_init(&scheduler->sigmngr);
    amxp_sigmngr_enable(&scheduler->sigmngr, true);
 
    scheduler->use_local_time = false;
    scheduler->timer = NULL;
    amxp_timer_new(&scheduler->timer, amxp_scheduler_trigger, scheduler);
    amxc_htable_init(&scheduler->items, 5);
    amxc_llist_init(&scheduler->ordered_items);
 
    rv = 0;
 
exit:
    return rv;
}

amxp_scheduler_new()

int amxp_scheduler_new

(

amxp_scheduler_t **

scheduler

)

Allocates a amxp_scheduler_t structures and initializes to an empty scheduler.

This function allocates a amxp_scheduler_t structure and initializes it to an empty scheduler.

An empty scheduler will be inactive (no timer is started) until the first schedule item is added.

By default the scheduler will be enabled. When adding schedule items they will be taken into account immediatly. If more control is needed, first disable the scheduler by calling amxp_scheduler_enable.

By default the scheduler will use UTC time, if all calculations needs to be done on local time call the function amxp_scheduler_use_local_time.

Use amxp_scheduler_set_cron_item, amxp_scheduler_set_cron_begin_end_item, amxp_scheduler_set_weekly_item or amxp_scheduler_set_weekly_begin_end_item to add schedule items.

Note

The allocated memory must be freed when not used anymore, use amxp_scheduler_delete to free the memory

Parameters

scheduler

pointer to a pointer that will point to the new allocated amxp_schedule_t structure

Returns

When allocation is successfull, this functions returns 0.

Definition at line 319 of file amxp_scheduler.c.

                                                     {
    int rv = -1;
 
    when_null(scheduler, exit);
    *scheduler = (amxp_scheduler_t*) calloc(1, sizeof(amxp_scheduler_t));
    when_null(*scheduler, exit);
 
    rv = amxp_scheduler_init(*scheduler);
 
exit:
    return rv;
}

amxp_scheduler_remove_item()

int amxp_scheduler_remove_item	(	amxp_scheduler_t *	scheduler,
		const char *	id
	)

Removes a schedule item from the scheduler.

Removes a schedule item with the provided identifier from the scheduler.

If the schedule item has a duration time which was started, the "stop:ID" signal be emitted when the item is removed.

When an identifier (ID) is specified, but no scheduler item with that identifier is available in this scheduler, the function succeeds but nothing happended.

Parameters

scheduler	pointer to an amxp_scheduler_t structure
id	the identifier for schedule item

Returns

When successfull, this functions returns 0.

Definition at line 647 of file amxp_scheduler.c.

                                               {
 
    int rv = -1;
    amxc_htable_it_t* hit = NULL;
    amxp_scheduler_item_t* item = NULL;
 
    when_null(scheduler, exit);
    when_str_empty(id, exit);
 
    hit = amxc_htable_get(&scheduler->items, id);
    when_null_status(hit, exit, rv = 0);
    item = amxc_container_of(hit, amxp_scheduler_item_t, hit);
 
    amxc_htable_it_take(hit);
    if((item->timer != NULL) && (item->timer->state == amxp_timer_running)) {
        amxp_timer_stop(item->timer);
        amxp_scheduler_emit(scheduler, item, "stop", 0, true);
    }
 
    amxp_scheduler_remove_signal(scheduler, "start", id);
    amxp_scheduler_remove_signal(scheduler, "stop", id);
    amxp_scheduler_remove_signal(scheduler, "trigger", id);
 
    amxc_llist_it_clean(&item->lit, amxp_schedule_item_delete);
    amxp_scheduler_reset_timer(scheduler);
 
    rv = 0;
 
exit:
    return rv;
}

amxp_scheduler_set_cron_begin_end_item()

int amxp_scheduler_set_cron_begin_end_item	(	amxp_scheduler_t *	scheduler,
		const char *	id,
		const char *	cron_begin,
		const char *	cron_end
	)

Adds a schedule item or updates a schedule item using a cron expressions.

Using a cron expression (see amxp_cron_expr_t) a schedule item is added to the scheduler. If a schedule item exists with the given identifier, it will be updated.

The scheduler will calculate the next time the schedule should be triggered using the cron expression provided with argument cron_begin.

A duration can be specified using a second cron expression (using argument cron_end). When the schedule item is triggered, the duration is calculated using the second cron expression.

For schedule items added with this function, the scheduler will emit the signal "start:ID" when the schedule is triggered and "stop:ID" when the next end time (duration) is reached.

Each signal will contain the schedule item identifier in the signal data and the reason (start, stop).

The signal "start:ID" will also contain the duration (in seconds) before the "stop:ID" will be send.

Schedule items with a duration for which the "start" signal was emitted and which are deleted before the duration is over, the scheduler will send a "stop" signal at the moment they are deleted.

Parameters

scheduler	pointer to an amxp_scheduler_t structure
id	the identifier for schedule item
cron_begin	a string containing a valid cron expression (see amxp_cron_expr_t)
cron_end	a string containing a valid cron expression (see amxp_cron_expr_t)

Returns

When successfull, this functions returns 0.

Definition at line 550 of file amxp_scheduler.c.

                                                                 {
    int rv = -1;
    amxp_scheduler_item_t* item = NULL;
 
    when_str_empty(cron_begin, exit);
    when_str_empty(cron_end, exit);
 
    item = amxp_scheduler_create_or_fetch(scheduler, id, 0);
    when_null(item, exit);
 
    item->end_time_is_set = true;
 
    rv = amxp_cron_parse_expr(&item->cron, cron_begin, NULL);
    when_failed(rv, exit);
    rv = amxp_cron_parse_expr(&item->end_cron, cron_end, NULL);
    when_failed(rv, exit);
 
    amxp_scheduler_insert(scheduler, id, item);
 
exit:
    if((rv != 0) && (item != NULL)) {
        amxc_llist_it_clean(&item->lit, amxp_schedule_item_delete);
    }
    return rv;
}

amxp_scheduler_set_cron_item()

int amxp_scheduler_set_cron_item	(	amxp_scheduler_t *	scheduler,
		const char *	id,
		const char *	cron_expr,
		uint32_t	duration
	)

Adds a schedule item or updates a schedule item using a cron expression.

Using a cron expression (see amxp_cron_expr_t) a schedule item is added to the scheduler. If a schedule item exists with the given identifier, it will be updated.

The scheduler will calculate the next time the schedule item should be triggered.

A duration can be specified. When the duration is not zero (0), the scheduler will emit the signal "start:ID" when the schedule is triggered, and starts a timer for the defined duration of the schedule item. When the timer expires the scheduler will emit the signal "stop:ID".

For schedule items that have a duration of zero (0), the scheduler will emit the signal "trigger:ID" when the schedule item is triggered.

Each signal will contain the schedule item identifier in the signal data and the reason (trigger, start, stop).

The signal "start:ID" will also contain the duration (in seconds) before the "stop:ID" will be send.

Schedule items with a duration for which the "start" signal was emitted and which are deleted before the duration is over, the scheduler will send a "stop" signal at the moment they are deleted.

Parameters

scheduler	pointer to an amxp_scheduler_t structure
id	the identifier for schedule item
cron_expr	a string containing a valid cron expression (see amxp_cron_expr_t)
duration	duration in seconds

Returns

When successfull, this functions returns 0.

Definition at line 524 of file amxp_scheduler.c.

                                                    {
    int rv = -1;
    amxp_scheduler_item_t* item = NULL;
 
    when_str_empty(cron_expr, exit);
 
    item = amxp_scheduler_create_or_fetch(scheduler, id, duration);
    when_null(item, exit);
 
    item->end_time_is_set = false;
 
    rv = amxp_cron_parse_expr(&item->cron, cron_expr, NULL);
    when_failed(rv, exit);
 
    amxp_scheduler_insert(scheduler, id, item);
 
exit:
    if((rv != 0) && (item != NULL)) {
        amxc_llist_it_clean(&item->lit, amxp_schedule_item_delete);
    }
    return rv;
}

amxp_scheduler_set_weekly_begin_end_item()

int amxp_scheduler_set_weekly_begin_end_item	(	amxp_scheduler_t *	scheduler,
		const char *	id,
		const char *	start_time,
		const char *	end_time,
		const char *	days_of_week
	)

Adds a schedule item or updates a schedule item using a start time, end time and list of week days.

Using a time in "HH:MM:SS" (seconds are optional) and a list of week days a schedule item is added to the scheduler. If a schedule item exists with the given identifier, it will be updated.

Weekdays must be specified with their name and are case insensitive

• sunday
• monday
• tuesday
• wednesday
• thursday
• friday
• saturday

Optionaly a range of weekdays can be specified. (sunday is considered the first day of the week).

Examples for days_of_Week argument:

"monday,tuesday,wednesday,thursday,friday"
"monday-friday"

The scheduler will calculate the next time the schedule should be triggered.

The duration is calculated using the end time. If the end time is smaller then the start time, the stop signal will be emitted the next valid day.

Example:

amxp_scheduler_set_weekly_begin_end_item(scheduler, "MyItem", "15:00", "12:00", "saturday,sunday");

When above schedule item is triggered (started) at a sunday at 15:00, the stop signal will be emitted on the next saterday at 12:00. So the item stays active for almost a full week.

Each signal will contain the schedule item identifier in the signal data and the reason (start, stop).

The signal "start:ID" will also contain the duration (in seconds) before the "stop:ID" signal will be send.

Schedule items with a duration for which the "start" signal was emitted and which are deleted before the duration is over, the scheduler will send a "stop" signal at the moment they are deleted.

Parameters

scheduler	pointer to an amxp_scheduler_t structure
id	the identifier for schedule item
start_time	a string containing a valid time in "HH:MM:SS" format, seconds are optional.
end_time	a string containing a valid time in "HH:MM:SS" format, seconds are optional.
days_of_week	a string containing comma separated list of week days or a range.

Returns

When successfull, this functions returns 0.

Definition at line 610 of file amxp_scheduler.c.

                                                                       {
    int rv = -1;
    amxp_scheduler_item_t* item = NULL;
 
    when_str_empty(days_of_week, exit);
 
    if((start_time == NULL) || (*start_time == 0)) {
        start_time = "00:00";
    }
 
    if((end_time == NULL) || (*end_time == 0)) {
        end_time = "23:59";
    }
 
    item = amxp_scheduler_create_or_fetch(scheduler, id, 0);
    when_null(item, exit);
 
    item->end_time_is_set = true;
 
    rv = amxp_cron_build_weekly(&item->cron, start_time, days_of_week);
    when_failed(rv, exit);
    rv = amxp_cron_build_weekly(&item->end_cron, end_time, days_of_week);
    when_failed(rv, exit);
 
    amxp_scheduler_insert(scheduler, id, item);
 
exit:
    if((rv != 0) && (item != NULL)) {
        amxc_llist_it_clean(&item->lit, amxp_schedule_item_delete);
    }
    return rv;
}

amxp_scheduler_set_weekly_item()

int amxp_scheduler_set_weekly_item	(	amxp_scheduler_t *	scheduler,
		const char *	id,
		const char *	time,
		const char *	days_of_week,
		uint32_t	duration
	)

Adds a schedule item or updates a schedule item using a time and list of week days.

Using a time in "HH:MM:SS" (seconds are optional) and a list of week days a schedule item is added to the scheduler. If a schedule item exists with the given identifier, it will be updated.

Weekdays must be specified with their name and are case insensitive

• sunday
• monday
• tuesday
• wednesday
• thursday
• friday
• saturday

Optionaly a range of weekdays can be specified. (sunday is considered the first day of the week).

Examples for days_of_Week argument:

"monday,tuesday,wednesday,thursday,friday"
"monday-friday"

The scheduler will calculate the next time the schedule should be triggered.

A duration can be specified. When the duration is not zero (0), the scheduler will emit the signal "start:ID" when the schedule is triggered, and starts a timer for the duration. When the timer expires the scheduler will emit the signal "stop:ID".

For schedule items that have a duration of zero (0), the scheduler will emit the signal "trigger:ID" when the schedule is triggered.

Each signal will contain the schedule item identifier in the signal data and the reason (start, stop).

The signal "start:ID" will also contain the duration (in seconds) before the "stop:ID" will be send.

Schedule items with a duration for which the "start" signal was emitted and which are deleted before the duration is over, the scheduler will send a "stop" signal at the moment they are deleted.

Parameters

scheduler	pointer to an amxp_scheduler_t structure
id	the identifier for schedule item
time	a string containing a valid time in "HH:MM:SS" format, seconds are optional.
days_of_week	a string containing comma separated list of week days or a range.
duration	duration in seconds

Returns

When successfull, this functions returns 0.

Definition at line 579 of file amxp_scheduler.c.

                                                      {
    int rv = -1;
    amxp_scheduler_item_t* item = NULL;
 
    when_str_empty(days_of_week, exit);
 
    if((time == NULL) || (*time == 0)) {
        time = "00:00";
    }
 
    item = amxp_scheduler_create_or_fetch(scheduler, id, duration);
    when_null(item, exit);
 
    item->end_time_is_set = false;
 
    rv = amxp_cron_build_weekly(&item->cron, time, days_of_week);
    when_failed(rv, exit);
 
    amxp_scheduler_insert(scheduler, id, item);
 
exit:
    if((rv != 0) && (item != NULL)) {
        amxc_llist_it_clean(&item->lit, amxp_schedule_item_delete);
    }
    return rv;
}

amxp_scheduler_update()

int amxp_scheduler_update

(

amxp_scheduler_t *

scheduler

)

Forces recalculation of the schedule items' next occurrence time.

Under normal circumstances there will be no need to call this function. The scheduler itself will do recalculation when needed by itself.

However this function can be called when system time changes, like NTP synchronizaton has happened.

Parameters

scheduler

pointer to an amxp_scheduler_t structure

Returns

When successfull, this functions returns 0.

Definition at line 418 of file amxp_scheduler.c.

                                                       {
    int rv = -1;
    amxc_ts_t now;
    amxp_scheduler_item_t* item = NULL;
 
    amxc_ts_now(&now);
    when_null(scheduler, exit);
 
    if(scheduler->use_local_time) {
        amxc_ts_to_local(&now);
    }
 
    amxc_llist_for_each(item_it, &scheduler->ordered_items) {
        item = amxc_container_of(item_it, amxp_scheduler_item_t, lit);
        amxp_cron_next(&item->cron, &now, &item->next);
        if(scheduler->sigmngr.enabled) {
            amxp_scheduler_check_item(scheduler, item);
        } else {
            amxp_timer_delete(&item->timer);
        }
    }
 
    amxp_scheduler_reset_timer(scheduler);
 
    rv = 0;
 
exit:
    return rv;
}

amxp_scheduler_use_local_time()

int amxp_scheduler_use_local_time	(	amxp_scheduler_t *	scheduler,
		bool	use_local_time
	)

Use local time or UTC time in calculation for next trigger times.

A scheduler calculates for each schedule item when the next occurence will be triggered, By default UTC time is used. Using this function the scheduler can be switched to use local time.

Parameters

scheduler	pointer to an amxp_scheduler_t structure
use_local_time	when set to true, the scheduler will use local time, when set to fals UTC time is used,

Returns

When successfull, this functions returns 0.

Definition at line 403 of file amxp_scheduler.c.

                                                                                    {
    int rv = -1;
 
    when_null(scheduler, exit);
 
    when_true_status(use_local_time == scheduler->use_local_time, exit, rv = 0);
    scheduler->use_local_time = use_local_time;
    amxp_scheduler_update(scheduler);
 
    rv = 0;
 
exit:
    return rv;
}