Awesome
<h1>The ecron application</h1>The ecron application
The Ecron application.
Authors: Francesca Gangemi (francesca@erlang-solutions.com), Ulf Wiger (ulf.wiger@erlang-solutions.com).
The Ecron application
The Ecron application executes scheduled functions.
A list of functions to execute might be specified in the ecron application
resource file as value of the scheduled environment variable.
Each entry specifies a job and must contain the scheduled time and a MFA
tuple {Module, Function, Arguments}.
It's also possible to configure options for a retry algorithm to run in case
MFA fails.
Seconds = integer() is the retry interval.
Retry = integer() | infinity is the number of times to retry.
Example of ecron.app
<pre> ... {env,[{scheduled, [{{{ '*', '*', '*'}, {0 ,0,0}}, {my_mod, my_fun1, Args}}, {{{ '*', 12 , 25}, {0 ,0,0}}, {my_mod, my_fun2, Args}}, {{{ '*', 1 , 1 }, {0 ,0,0}}, {my_mod, my_fun3, Args}, infinity, 60}, {{{2010, 1 , 1 }, {12,0,0}}, {my_mod, my_fun3, Args}}, {{{ '*', 12 ,last}, {0 ,0,0}}, {my_mod, my_fun4, Args}]}]}, ... </pre>Once the ecron application is started, it's possible to dynamically add new
jobs using the ecron:insert/2 or ecron:insert/4
API.
The MFA is executed when a task is set to run.
The MFA has to return ok, {ok, Data}, {apply, fun()}
or {error, Reason}.
If {error, Reason} is returned and the job was defined with retry options
(Retry and Seconds were specified together with the MFA) then ecron will try
to execute MFA later according to the given configuration.
The MFA may return {apply, fun()} where fun() has arity zero.
fun will be immediately executed after MFA execution.
The fun has to return ok, {ok, Data} or {error, Reason}.
If the MFA or fun terminates abnormally or returns an invalid
data type (not ok, {ok, Data} or {error, Reason}), an event
is forwarded to the event manager and no retries are executed.
If the return value of the fun is {error, Reason} and retry
options were given in the job specification then the fun is
rescheduled to be executed after the configurable amount of time.
Data which does not change between retries of the fun
must be calculated outside the scope of the fun.
Data which changes between retries has to be calculated within the scope
of the fun.
<br></br>
In the following example, ScheduleTime will change each time the function is scheduled, while ExecutionTime will change for every retry. If static data has to persist across calls or retries, this is done through a function in the MFA or the fun.
<pre> print() -> ScheduledTime = time(), {apply, fun() -> ExecutionTime = time(), io:format("Scheduled:~p~n",[ScheduledTime]), io:format("Execution:~p~n",[ExecutionTime]), {error, retry} end}. </pre>Event handlers may be configured in the application resource file specifying for each of them, a tuple as the following:
<pre>{Handler, Args} Handler = Module | {Module,Id} Module = atom() Id = term() Args = term() </pre>Module:init/1 will be called to initiate the event handler and
its internal state
<br></br>
<br></br>
Example of ecron.app
<pre> ... {env, [{event_handlers, [{ecron_event, []}]}]}, ... </pre>The API add_event_handler/2 and
delete_event_handler/1
allow user to dynamically add and remove event handlers.
All the configured event handlers will receive the following events:
{mfa_result, Result, {Schedule, {M, F, A}}, DueDateTime, ExecutionDateTime}
when MFA is executed.
{fun_result, Result, {Schedule, {M, F, A}}, DueDateTime, ExecutionDateTime}
when fun is executed.
{retry, {Schedule, MFA}, Fun, DueDateTime}
when MFA, or fun, is rescheduled to be executed later after a failure.
{max_retry, {Schedule, MFA}, Fun, DueDateTime} when MFA,
or fun has reached maximum number of retry specified when
the job was inserted.
Result is the return value of MFA or fun.
If an exception occurs during evaluation of MFA, or fun, then
it's caught and sent in the event.
(E.g. Result = {'EXIT',{Reason,Stack}}).
Schedule = {Date, Time} as given when the job was inserted, E.g.
{{'*','*','*'}, {0,0,0}}
<br></br>
DueDateTime = {Date, Time} is the exact Date and Time when the MFA,
or the fun, was supposed to run.
E.g. {{2010,1,1}, {0,0,0}}
<br></br>
ExecutionDateTime = {Date, Time} is the exact Date and Time
when the MFA, or the fun, was executed.
<br></br>
<br></br>
<br></br>
If a node is restarted while there are jobs in the list then these jobs are
not lost. When Ecron starts it takes a list of scheduled MFA from the
environment variable scheduled and inserts them into a persistent table
(mnesia). If an entry of the scheduled MFA specifies the same parameters
values of a job already present in the table then the entry won't be inserted
avoiding duplicated jobs.
<br></br>
No duplicated are removed from the MFA list configured in the scheduled variable.