View Source ecron (ecron v1.0.1)
Summary
Functions
Equivalent to activate(ecron_local, Name).
Activates a previously deactivated job. The job will resume from the current time.
Equivalent to add(ecron_local, JobName, Spec, MFA).
Equivalent to add(Register, JobName, Spec, MFA, unlimited, unlimited, []).
Equivalent to add(ecron_local, name(), Spec, MFA, Start, End, []).
Adds a new crontab job with specified parameters. Jobs exceeding their limits are automatically removed.
Equivalent to add_with_count(ecron_local, make_ref(), Spec, MFA, RunCount).
Equivalent to add(ecron_local, name(), Spec, MFA, Start, End, []).
Equivalent to add(register(), name(), Spec, MFA, Start, End, []).
Equivalent to deactivate(ecron_local, Name).
Deactivates an existing job temporarily. The job can be reactivated using activate/2.
Equivalent to delete(ecron_local, Name).
Deletes an existing job. If the job does not exist, it will be ignored.
Parses a crontab specification and returns the next N trigger times. Useful for debugging and validating crontab expressions.
Reloads all tasks manually. Useful when system time has changed significantly.
Creates a one-time timer that sends a message when the crontab spec is triggered.
Sends a message to a process repeatedly based on a crontab schedule.
Retrieves statistics for both local and global registered jobs.
Retrieves statistics for local registered jobs.
Retrieves statistics for a specific job.
Types
-type crontab() ::
#{second => '*' | [0..59 | {0..58, 1..59}, ...],
minute => '*' | [0..59 | {0..58, 1..59}, ...],
hour => '*' | [0..23, ...],
month => '*' | [1..12 | {1..11, 2..12}, ...],
day_of_month => '*' | [1..31 | {1..30, 2..31}, ...],
day_of_week => '*' | [0..6 | {0..5, 1..6}, ...]}.
-type ecron() :: #{name => name(), crontab => crontab(), start_time => rfc3339_string() | unlimited, end_time => rfc3339_string() | unlimited, mfa => mfargs(), type => cron | every}.
-type ecron_result() :: {ok, name()} | {error, parse_error(), term()} | {error, already_exist}.
-type end_at() :: unlimited | calendar:time().
-type name() :: term().
-type option() :: {singleton, boolean()} | {max_count, pos_integer() | unlimited}.
-type options() :: [option()].
-type parse_error() ::
invalid_time | invalid_spec | month | day_of_month | day_of_week | hour | minute | second.
-type register() :: atom().
-type rfc3339_string() :: [byte(), ...].
-type start_at() :: unlimited | calendar:time().
-type statistic() :: #{ecron => ecron(), status => status(), failed => non_neg_integer(), ok => non_neg_integer(), results => [term()], run_microsecond => [pos_integer()], time_zone => local | utc, worker => pid(), next => [calendar:datetime()]}.
-type status() :: deactivate | activate.
Functions
-spec activate(name()) -> ok | {error, not_found}.
Equivalent to activate(ecron_local, Name).
Activates a previously deactivated job. The job will resume from the current time.
Parameters:
Register
- Process name where job is registeredJobName
- Name of job to activate
Returns: ok
| {error, not_found}
-spec add(name(), crontab_spec(), mfargs()) -> ecron_result().
Equivalent to add(ecron_local, JobName, Spec, MFA).
-spec add(register(), name(), crontab_spec(), mfargs()) -> ecron_result().
Equivalent to add(Register, JobName, Spec, MFA, unlimited, unlimited, []).
-spec add(name(), crontab_spec(), mfargs(), start_at(), end_at(), options()) -> ecron_result().
Equivalent to add(ecron_local, name(), Spec, MFA, Start, End, []).
-spec add(register(), name(), crontab_spec(), mfargs(), start_at(), end_at(), options()) -> ecron_result().
Adds a new crontab job with specified parameters. Jobs exceeding their limits are automatically removed.
Parameters:
Register
- The process name where the job will be registeredJobName
- Unique identifier for the job. Returns{error, already_exist}
if duplicateSpec
- Crontab expression defining execution scheduleMFA
-{Module, Function, Args}
to execute when triggeredStart
- Start time{Hour,Min,Sec}
orunlimited
for immediate startEnd
- End time{Hour,Min,Sec}
orunlimited
for no endOpts
- Options list:{singleton, boolean()}
- If true (default), prevents concurrent execution{max_count, pos_integer() | unlimited}
- Maximum executions allowed
Returns: {ok, JobName}
| {error, already_exist}
| {error, parse_error(), term()}
-spec add_with_count(crontab_spec(), mfargs(), pos_integer()) -> ecron_result().
Equivalent to add_with_count(ecron_local, make_ref(), Spec, MFA, RunCount).
-spec add_with_count(register(), name(), crontab_spec(), mfargs(), pos_integer()) -> ecron_result().
Equivalent to add(register(), make_ref(), Spec, MFA, unlimited, unlimited, [{max_count, RunCount}]).
-spec add_with_time(name(), crontab_spec(), mfargs(), start_at(), end_at()) -> ecron_result().
Equivalent to add(ecron_local, name(), Spec, MFA, Start, End, []).
-spec add_with_time(register(), name(), crontab_spec(), mfargs(), start_at(), end_at()) -> ecron_result().
Equivalent to add(register(), name(), Spec, MFA, Start, End, []).
-spec deactivate(name()) -> ok | {error, not_found}.
Equivalent to deactivate(ecron_local, Name).
Deactivates an existing job temporarily. The job can be reactivated using activate/2.
Parameters:
Register
- Process name where job is registeredJobName
- Name of job to deactivate
Returns: ok
| {error, not_found}
-spec delete(name()) -> ok.
Equivalent to delete(ecron_local, Name).
Deletes an existing job. If the job does not exist, it will be ignored.
Parameters:
Register
- Process name where job is registeredJobName
- Name of job to delete
Returns: ok
-spec parse_spec(crontab_spec(), pos_integer()) -> {ok, #{type => cron | every, crontab => crontab_spec(), next => [rfc3339_string()]}} | {error, atom(), term()}.
Parses a crontab specification and returns the next N trigger times. Useful for debugging and validating crontab expressions.
Parameters:
Spec
- Crontab expression to parseNum
- Number of future trigger times to calculate
Returns: {ok, #{type => cron|every, crontab => parsed_spec, next => [rfc3339_string()]}}
| {error, parse_error(), term()}
-spec reload() -> ok.
Reloads all tasks manually. Useful when system time has changed significantly.
This will:
- Recalculate next execution times for all jobs
- Reset internal timers
- Apply to both local and global jobs
Returns: ok
-spec send_after(crontab_spec(), pid() | atom(), term()) -> {ok, reference()} | {error, parse_error(), term()}.
Creates a one-time timer that sends a message when the crontab spec is triggered.
Parameters:
Spec
- Crontab expression defining when to triggerDest
- Destination pid() or registered name to receive messageMessage
- Term to send when timer triggers
Notes:
- Similar to erlang:send_after/3 but uses crontab format
- Dest pid must be local
- Maximum time value is 4294967295 milliseconds
- Timer auto-cancels if destination process dies
- Use erlang:cancel_timer/1 to cancel, not ecron:delete/1
Returns: {ok, reference()}
| {error, parse_error(), term()}
-spec send_interval(crontab_spec(), pid(), term()) -> ecron_result().
Equivalent to send_interval(ecron_local, make_ref(), Spec, Pid, Message, unlimited, unlimited, []).
-spec send_interval(register(), name(), crontab_spec(), pid(), term()) -> ecron_result().
Equivalent to send_interval(ecron_local, name(), Spec, Pid, Message, unlimited, unlimited, []).
-spec send_interval(register(), name(), crontab_spec(), term(), start_at(), end_at(), options()) -> ecron_result().
Equivalent to send_interval(register(), name(), Spec, self(), Message, Start, End, Option).
-spec send_interval(register(), name(), crontab_spec(), pid(), term(), start_at(), end_at(), options()) -> ecron_result().
Sends a message to a process repeatedly based on a crontab schedule.
Parameters:
Register
- Process name where job will be registeredJobName
- Unique identifier for the jobSpec
- Crontab expression defining execution schedulePid
- Destination process ID or registered nameMessage
- Term to send on each triggerStart
- Start time{Hour,Min,Sec}
orunlimited
End
- End time{Hour,Min,Sec}
orunlimited
Option
- Same options as add/7
Returns: Same as add/7
-spec statistic() -> [statistic()].
Retrieves statistics for both local and global registered jobs.
Returns: List of statistics for all jobs in both local and global registries. Each statistic entry contains the same information as statistic/2.
Retrieves statistics for local registered jobs.
Returns: List of statistics for all jobs in local registries. Each statistic entry contains the same information as statistic/2.
Retrieves statistics for a specific job.
Parameters:
Register
- Process name where job is registeredJobName
- Name of job to get statistics for
Returns: {ok, statistic()}
| {error, not_found}
Where statistic() contains:
- Job configuration
- Execution counts (success/failure)
- Latest results
- Run times
- Next scheduled runs