Task runner schedule APIs

Task runner schedule API. More...

Data Structures
struct	task_schedule_tdf_logging
	Control TDF logging output of a task. More...
struct	task_schedule_state_conditions
	Schedule state conditions. More...
struct	task_schedule
	Schedule for a given task. More...
struct	task_schedule_state
	State for a given task schedule. More...

Macros
#define	TR_NOT   0x100
	Invert the state.
#define	TR_OR   0x200
	OR the state with the previous result.
#define	TR_AND   0x00
	AND the state with the previous result.
#define	TASK_STATES_DEFINE(...)
	Helper for constructing a task_schedule_state_conditions struct.
#define	TASK_STATES_START_TIMEOUT(seconds)
	Helper macro to initialise states_start_timeout_2x_s
#define	TASK_RUNNER_LOCKOUT_IGNORE_FIRST   BIT(31)
	Normally the lockout period must elapse after boot before the periodicity check passes.
#define	TASK_SCHEDULE_STATES_DEFINE(name, schedules)
	Instantiate schedule state array.

Typedefs
typedef void(*	task_schedule_event_cb_t) (const struct task_schedule *schedule, enum task_schedule_event event)
	Callback notifying that an event has occurred on a schedule.

Enumerations
enum	task_runner_valid_type {   TASK_LOCKED = 0x80 , TASK_VALID_ALWAYS = 1 , TASK_VALID_ACTIVE = 2 , TASK_VALID_INACTIVE = 3 ,   TASK_VALID_PERMANENTLY_RUNS = 4 }
enum	task_runner_periodicity_type { TASK_PERIODICITY_FIXED = 1 , TASK_PERIODICITY_LOCKOUT = 2 , TASK_PERIODICITY_AFTER = 3 , TASK_PERIODICITY_LOCKOUT_DYNAMIC_BATTERY = 4 }
enum	task_schedule_event { TASK_SCHEDULE_STARTED = 0 , TASK_SCHEDULE_TERMINATE_REQUEST = 1 , TASK_SCHEDULE_STOPPED = 2 }
	Events that can trigger callbacks. More...

Functions
bool	task_schedule_validate (const struct task_schedule *schedule)
	Basic validity checking on task schedules.
bool	task_schedule_should_start (const struct task_schedule *schedule, struct task_schedule_state *state, atomic_t *app_states, uint32_t uptime, uint32_t epoch_time, uint8_t battery)
	Determine whether a task should start executing.
bool	task_schedule_should_terminate (const struct task_schedule *schedule, struct task_schedule_state *state, atomic_t *app_states, uint32_t uptime, uint32_t epoch_time, uint8_t battery)
	Determine whether a task should be terminated.

Detailed Description

Task runner schedule API.

Macro Definition Documentation

TASK_RUNNER_LOCKOUT_IGNORE_FIRST

#define TASK_RUNNER_LOCKOUT_IGNORE_FIRST   BIT(31)

#include </__w/infuse-sdk/infuse-sdk/infuse-sdk/include/infuse/task_runner/schedule.h>

Normally the lockout period must elapse after boot before the periodicity check passes.

Apply to task_schedule.periodicity.lockout.lockout_s for the periodicity check to always pass before the schedule runs for the first time.

TASK_SCHEDULE_STATES_DEFINE

#define TASK_SCHEDULE_STATES_DEFINE	(		name,
			schedules )

#include </__w/infuse-sdk/infuse-sdk/infuse-sdk/include/infuse/task_runner/schedule.h>

Value:

        static struct task_schedule_state name[_TASK_SCHEDULE_MAX_SCHEDULES(schedules)]

Instantiate schedule state array.

If loading schedules from the KV store is enabled, the array is sized to the maximum number of schedules possible. Otherwise, it is sized to the number of default schedules.

Parameters

name	Name of the schedule state array
schedules	Array of default schedules

TASK_STATES_DEFINE

#define TASK_STATES_DEFINE

(

...

)

#include </__w/infuse-sdk/infuse-sdk/infuse-sdk/include/infuse/task_runner/schedule.h>

Value:

        _TR_GET_MACRO(__VA_ARGS__, _TR_STATES_4, _TR_STATES_3, _TR_STATES_2, _TR_STATES_1)         \
        (__VA_ARGS__)

Helper for constructing a task_schedule_state_conditions struct.

Each provided state can be optionally inverted (with TR_NOT). Each provided state is evaluated with the following priority: (((S0 OP S1) OP S2) OP S3) By default, the OP between each state is AND (&&), but this can be switched to OR (||) by specifying TR_OR on S1, S2, or S3.

struct state_control test1 = TASK_STATES_DEFINE(10);
struct state_control test2 = TASK_STATES_DEFINE(10, 11, 45, 200);
struct state_control test3 = TASK_STATES_DEFINE(TR_NOT | 34, 12, TR_NOT | 99);
 struct state_control test4 = TASK_STATES_DEFINE(TR_NOT | 34, TR_OR | 12, TR_OR | TR_NOT | 99);

Parameters

...	Variable number of states (up to 4) which are evaluated together.

TASK_STATES_START_TIMEOUT

#define TASK_STATES_START_TIMEOUT

(

seconds

)

#include </__w/infuse-sdk/infuse-sdk/infuse-sdk/include/infuse/task_runner/schedule.h>

Value:

((seconds) / 2)

Helper macro to initialise states_start_timeout_2x_s

Maximum value is 2 * UINT16_MAX, just over 34 hours.

Parameters

seconds

Desired timeout in seconds

Return values

Value

for use with states_start_timeout_2x_s

TR_AND

#define TR_AND   0x00

#include </__w/infuse-sdk/infuse-sdk/infuse-sdk/include/infuse/task_runner/schedule.h>

AND the state with the previous result.

TR_NOT

#define TR_NOT   0x100

#include </__w/infuse-sdk/infuse-sdk/infuse-sdk/include/infuse/task_runner/schedule.h>

Invert the state.

TR_OR

#define TR_OR   0x200

#include </__w/infuse-sdk/infuse-sdk/infuse-sdk/include/infuse/task_runner/schedule.h>

OR the state with the previous result.

Typedef Documentation

task_schedule_event_cb_t

typedef void(* task_schedule_event_cb_t) (const struct task_schedule *schedule, enum task_schedule_event event)

#include </__w/infuse-sdk/infuse-sdk/infuse-sdk/include/infuse/task_runner/schedule.h>

Callback notifying that an event has occurred on a schedule.

Note

Callback can only be assigned to the task_schedule_state AFTER the call to task_runner_init.

Parameters

schedule	Schedule with the event
event	Event that occurred

Enumeration Type Documentation

task_runner_periodicity_type

enum task_runner_periodicity_type

#include </__w/infuse-sdk/infuse-sdk/infuse-sdk/include/infuse/task_runner/schedule.h>

Enumerator
TASK_PERIODICITY_FIXED	Task can only run on N second boundaries.
TASK_PERIODICITY_LOCKOUT	Task can only run N seconds after previous run started.
TASK_PERIODICITY_AFTER	Task can only run N seconds after another schedule terminates.
TASK_PERIODICITY_LOCKOUT_DYNAMIC_BATTERY	TASK_PERIODICITY_LOCKOUT with a dynamic lockout based on battery charge

task_runner_valid_type

enum task_runner_valid_type

#include </__w/infuse-sdk/infuse-sdk/infuse-sdk/include/infuse/task_runner/schedule.h>

Enumerator
TASK_LOCKED	Do not update definition from KV store.
TASK_VALID_ALWAYS	Task is always valid.
TASK_VALID_ACTIVE	Task is only valid when INFUSE_STATE_APPLICATION_ACTIVE is set.
TASK_VALID_INACTIVE	Task is only valid when INFUSE_STATE_APPLICATION_ACTIVE is not set.
TASK_VALID_PERMANENTLY_RUNS	Entry and exit conditions never checked, task is rebooted if it terminates.

task_schedule_event

enum task_schedule_event

#include </__w/infuse-sdk/infuse-sdk/infuse-sdk/include/infuse/task_runner/schedule.h>

Events that can trigger callbacks.

Enumerator
TASK_SCHEDULE_STARTED	Task associated with the schedule has been started.
TASK_SCHEDULE_TERMINATE_REQUEST	Task associated with the schedule has been requested to terminate.
TASK_SCHEDULE_STOPPED	Task associated with the schedule has stopped.

Function Documentation

task_schedule_should_start()

bool task_schedule_should_start	(	const struct task_schedule *	schedule,
		struct task_schedule_state *	state,
		atomic_t *	app_states,
		uint32_t	uptime,
		uint32_t	epoch_time,
		uint8_t	battery )

#include </__w/infuse-sdk/infuse-sdk/infuse-sdk/include/infuse/task_runner/schedule.h>

Determine whether a task should start executing.

Parameters

schedule	Task schedule to evaluate
state	Previous state of the schedule
app_states	Current application states
uptime	Current system uptime in seconds
epoch_time	Current epoch time (GPS time) in seconds
battery	Battery charge percent

Return values

true	Task should be started
false	Task should not be started

task_schedule_should_terminate()

bool task_schedule_should_terminate	(	const struct task_schedule *	schedule,
		struct task_schedule_state *	state,
		atomic_t *	app_states,
		uint32_t	uptime,
		uint32_t	epoch_time,
		uint8_t	battery )

#include </__w/infuse-sdk/infuse-sdk/infuse-sdk/include/infuse/task_runner/schedule.h>

Determine whether a task should be terminated.

Parameters

schedule	Task schedule to evaluate
state	Previous state of the schedule
app_states	Current application states
uptime	Current system uptime in seconds
epoch_time	Current epoch time (GPS time) in seconds
battery	Battery charge percent

Return values

true	Task should be terminated
false	Task should not be terminated

task_schedule_validate()

bool task_schedule_validate

(

const struct task_schedule *

schedule

)

#include </__w/infuse-sdk/infuse-sdk/infuse-sdk/include/infuse/task_runner/schedule.h>

Basic validity checking on task schedules.

Note

This function checks for schedules that would lead to divide-by-zero or similar errors, not for schedules that will never execute.

Parameters

schedule

Schedule to validate

Return values

true	If schedule doesn't contain invalid parameters
false	If schedule contains invalid parameters