Cron

Wall-clock timers, for alarms, calendar events and the like. More...

Data Structures
struct	pbl_cron_job
	Cron job. More...
union	pbl_cron_job.__unnamed13__
struct	pbl_cron_job.__unnamed13__.__unnamed15__

Macros
#define	PBL_CRON_MINUTE_ANY   (-1)
	Any minute.
#define	PBL_CRON_HOUR_ANY   (-1)
	Any hour.
#define	PBL_CRON_MDAY_ANY   (-1)
	Any day of the month.
#define	PBL_CRON_MONTH_ANY   (-1)
	Any month.
#define	PBL_CRON_WDAY_SUNDAY   (1 << 0)
	Sunday in a day of the week mask.
#define	PBL_CRON_WDAY_MONDAY   (1 << 1)
	Monday in a day of the week mask.
#define	PBL_CRON_WDAY_TUESDAY   (1 << 2)
	Tuesday in a day of the week mask.
#define	PBL_CRON_WDAY_WEDNESDAY   (1 << 3)
	Wednesday in a day of the week mask.
#define	PBL_CRON_WDAY_THURSDAY   (1 << 4)
	Thursday in a day of the week mask.
#define	PBL_CRON_WDAY_FRIDAY   (1 << 5)
	Friday in a day of the week mask.
#define	PBL_CRON_WDAY_SATURDAY   (1 << 6)
	Saturday in a day of the week mask.
#define	PBL_CRON_WDAY_WEEKDAYS
	Monday to Friday.
#define	PBL_CRON_WDAY_WEEKENDS   (PBL_CRON_WDAY_SUNDAY | PBL_CRON_WDAY_SATURDAY)
	Saturday and Sunday.
#define	PBL_CRON_WDAY_ANY   (PBL_CRON_WDAY_WEEKENDS | PBL_CRON_WDAY_WEEKDAYS)
	Every day of the week.

Typedefs
typedef void(*	pbl_cron_job_cb_t) (struct pbl_cron_job *job, void *data)
	Callback of a cron job.

Functions
void	pbl_cron_init (void)
	Initialize the cron subsystem.
void	pbl_cron_handle_clock_change (int32_t utc_time_delta, int32_t gmt_offset_delta, bool dst_changed)
	Adjust the scheduled jobs after a wall clock change.
void	pbl_cron_handle_clock_correction (void)
	Catch up with a small correction of the wall clock.
time_t	pbl_cron_job_schedule (struct pbl_cron_job *job)
	Schedule a job, or reschedule it if already scheduled.
void	pbl_cron_job_schedule_at (struct pbl_cron_job *job, time_t utc_time)
	Schedule a job at a fixed time, or reschedule it if already scheduled.
time_t	pbl_cron_job_schedule_after (struct pbl_cron_job *job, struct pbl_cron_job *new_job)
	Schedule a job to run right after another one.
bool	pbl_cron_job_unschedule (struct pbl_cron_job *job)
	Unschedule a job.
bool	pbl_cron_job_is_scheduled (struct pbl_cron_job *job)
	Check whether a job is scheduled.
time_t	pbl_cron_job_get_execute_time (const struct pbl_cron_job *job)
	Compute the next execution time of a job from the current time.
time_t	pbl_cron_job_get_execute_time_from_epoch (const struct pbl_cron_job *job, time_t local_epoch)
	Compute the next execution time of a job from a given time.

Detailed Description

Wall-clock timers, for alarms, calendar events and the like.

A job matches a set of local times, like a crontab entry: each of the minute, hour, day of the month and month fields is a value or "any", and the days of the week are a mask. Scheduling a job computes its next matching time; the job fires once, then is unscheduled. DST transitions are handled, and clock changes recompute the execution times as configured per job.

Callbacks run on the NewTimers thread, or on the caller of pbl_cron_handle_clock_change() for the jobs it finds due, without the cron lock held, so they may reschedule their own job. The job structures are owned by the caller and must stay valid while scheduled.

static void prv_alarm_fired(struct pbl_cron_job *job, void *data) {
  ...
  pbl_cron_job_schedule(job);  // fire again on the next match
}
 
static struct pbl_cron_job s_alarm = {
  .cb = prv_alarm_fired,
  .minute = 30,
  .hour = 7,
  .mday = PBL_CRON_MDAY_ANY,
  .month = PBL_CRON_MONTH_ANY,
  .wday = PBL_CRON_WDAY_WEEKDAYS,
  .clock_change_tolerance = 60,
};
 
time_t when = pbl_cron_job_schedule(&s_alarm);  // next weekday at 07:30

---

Data Structure Documentation

pbl_cron_job

struct pbl_cron_job

Cron job.

Fill in the schedule and callback, then call pbl_cron_job_schedule().

Data Fields
union pbl_cron_job.__unnamed13__	__unnamed__
bool	absolute	Scheduled with pbl_cron_job_schedule_at(); internal.
time_t	cached_execute_time	Execution time in seconds since the epoch, set by pbl_cron_job_schedule(). Must not be changed while the job is scheduled.
pbl_cron_job_cb_t	cb	Called when the job fires.
void *	cb_data	Data passed to cb.
uint32_t	clock_change_tolerance	Clock change, in seconds, from which the execution time is recalculated. A time zone or DST change always recalculates. A change of the time itself (set by the user or by the phone) recalculates when it is at least this large, so 0 always recalculates and UINT32_MAX never does. A recalculated job that was skipped over waits for its next match; a job that is not recalculated and was skipped over fires immediately.
int8_t	hour	Hour, 0 to 23, or PBL_CRON_HOUR_ANY.
ListNode	list_node	Node in the list of scheduled jobs; internal.
int8_t	mday	Day of the month, 0-based (0 to 30), or PBL_CRON_MDAY_ANY.
int8_t	minute	Minute, 0 to 59, or PBL_CRON_MINUTE_ANY.
int8_t	month	Month, 0 to 11, or PBL_CRON_MONTH_ANY.
int32_t	offset_seconds	Offset in seconds applied to the matched time. A job for Monday 0:15 with an offset of -1800 fires on Sunday at 23:45.

pbl_cron_job.__unnamed13__

union pbl_cron_job.__unnamed13__

Data Fields
struct pbl_cron_job.__unnamed13__.__unnamed15__	__unnamed__
uint8_t	flags	All flags.

pbl_cron_job.__unnamed13__.__unnamed15__

struct pbl_cron_job.__unnamed13__.__unnamed15__

Data Fields
bool	may_be_instant: 1	Allow the execution time to be the current time, for events that must happen at the specified time even if that is right now.
uint8_t	wday: 7	Days of the week, a PBL_CRON_WDAY_ mask; 0 acts like PBL_CRON_WDAY_ANY.

Macro Definition Documentation

PBL_CRON_HOUR_ANY

#define PBL_CRON_HOUR_ANY   (-1)

Any hour.

PBL_CRON_MDAY_ANY

#define PBL_CRON_MDAY_ANY   (-1)

Any day of the month.

PBL_CRON_MINUTE_ANY

#define PBL_CRON_MINUTE_ANY   (-1)

Any minute.

PBL_CRON_MONTH_ANY

#define PBL_CRON_MONTH_ANY   (-1)

Any month.

PBL_CRON_WDAY_ANY

#define PBL_CRON_WDAY_ANY   (PBL_CRON_WDAY_WEEKENDS | PBL_CRON_WDAY_WEEKDAYS)

Every day of the week.

PBL_CRON_WDAY_FRIDAY

#define PBL_CRON_WDAY_FRIDAY   (1 << 5)

Friday in a day of the week mask.

PBL_CRON_WDAY_MONDAY

#define PBL_CRON_WDAY_MONDAY   (1 << 1)

Monday in a day of the week mask.

PBL_CRON_WDAY_SATURDAY

#define PBL_CRON_WDAY_SATURDAY   (1 << 6)

Saturday in a day of the week mask.

PBL_CRON_WDAY_SUNDAY

#define PBL_CRON_WDAY_SUNDAY   (1 << 0)

Sunday in a day of the week mask.

PBL_CRON_WDAY_THURSDAY

#define PBL_CRON_WDAY_THURSDAY   (1 << 4)

Thursday in a day of the week mask.

PBL_CRON_WDAY_TUESDAY

#define PBL_CRON_WDAY_TUESDAY   (1 << 2)

Tuesday in a day of the week mask.

PBL_CRON_WDAY_WEDNESDAY

#define PBL_CRON_WDAY_WEDNESDAY   (1 << 3)

Wednesday in a day of the week mask.

PBL_CRON_WDAY_WEEKDAYS

#define PBL_CRON_WDAY_WEEKDAYS

Value:

  (PBL_CRON_WDAY_MONDAY | PBL_CRON_WDAY_TUESDAY | PBL_CRON_WDAY_WEDNESDAY | \
   PBL_CRON_WDAY_THURSDAY | PBL_CRON_WDAY_FRIDAY)

Monday to Friday.

PBL_CRON_WDAY_WEEKENDS

#define PBL_CRON_WDAY_WEEKENDS   (PBL_CRON_WDAY_SUNDAY | PBL_CRON_WDAY_SATURDAY)

Saturday and Sunday.

Typedef Documentation

pbl_cron_job_cb_t

typedef void(* pbl_cron_job_cb_t) (struct pbl_cron_job *job, void *data)

Callback of a cron job.

The job is already unscheduled when the callback runs.

Parameters

job	Job that fired.
data	pbl_cron_job::cb_data.

Function Documentation

pbl_cron_handle_clock_change()

void pbl_cron_handle_clock_change	(	int32_t	utc_time_delta,
		int32_t	gmt_offset_delta,
		bool	dst_changed
	)

Adjust the scheduled jobs after a wall clock change.

Recalculates execution times as described for pbl_cron_job::clock_change_tolerance, then runs the jobs that are due.

Parameters

utc_time_delta	Seconds the UTC time moved by.
gmt_offset_delta	Seconds the GMT offset moved by; non-zero forces recalculation.
dst_changed	Whether the DST state changed; true forces recalculation.

pbl_cron_handle_clock_correction()

void pbl_cron_handle_clock_correction

(

void

)

Catch up with a small correction of the wall clock.

For corrections too small to recalculate execution times for: re-arms the wakeup timer for the corrected time and runs the jobs that are now due.

pbl_cron_init()

void pbl_cron_init

(

void

)

Initialize the cron subsystem.

pbl_cron_job_get_execute_time()

time_t pbl_cron_job_get_execute_time

(

const struct pbl_cron_job *

job

)

Compute the next execution time of a job from the current time.

Parameters

job

Job.

Returns

Execution time, in seconds since the epoch.

pbl_cron_job_get_execute_time_from_epoch()

time_t pbl_cron_job_get_execute_time_from_epoch	(	const struct pbl_cron_job *	job,
		time_t	local_epoch
	)

Compute the next execution time of a job from a given time.

Parameters

job	Job.
local_epoch	Time to compute from, in seconds since the epoch.

Returns

Execution time, in seconds since the epoch.

pbl_cron_job_is_scheduled()

bool pbl_cron_job_is_scheduled

(

struct pbl_cron_job *

job

)

Check whether a job is scheduled.

Parameters

job

Job.

Returns

true if scheduled.

pbl_cron_job_schedule()

time_t pbl_cron_job_schedule

(

struct pbl_cron_job *

job

)

Schedule a job, or reschedule it if already scheduled.

The job runs once, at its next matching time. The subsystem references the job until it fires or is unscheduled.

Parameters

job

Job.

Returns

Execution time, in seconds since the epoch.

pbl_cron_job_schedule_after()

time_t pbl_cron_job_schedule_after	(	struct pbl_cron_job *	job,
		struct pbl_cron_job *	new_job
	)

Schedule a job to run right after another one.

new_job takes the schedule of job and keeps its own callback and data. It fires after job, though not necessarily immediately after.

Parameters

job	Scheduled job.
new_job	Job to schedule, not scheduled.

Returns

Execution time, in seconds since the epoch.

pbl_cron_job_schedule_at()

void pbl_cron_job_schedule_at	(	struct pbl_cron_job *	job,
		time_t	utc_time
	)

Schedule a job at a fixed time, or reschedule it if already scheduled.

The job runs once at utc_time; its schedule fields are ignored. The time does not follow time zone, DST or clock changes: a job the clock is moved past runs right away.

Parameters

job	Job.
utc_time	Execution time, in seconds since the epoch.

pbl_cron_job_unschedule()

bool pbl_cron_job_unschedule

(

struct pbl_cron_job *

job

)

Unschedule a job.

Parameters

job

Job.

Returns

true if the job was removed, false if it was not scheduled (including while its callback runs).