View Source ecron (ecron v1.0.1)

Summary

Functions

Activates a previously deactivated job. The job will resume from the current time.

Adds a new crontab job with specified parameters. Jobs exceeding their limits are automatically removed.

Deactivates an existing job temporarily. The job can be reactivated using activate/2.

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

crontab/0

-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}, ...]}.

crontab_spec/0

-type crontab_spec() :: crontab() | string() | binary() | 1..4294967.

ecron/0

-type ecron() ::
          #{name => name(),
            crontab => crontab(),
            start_time => rfc3339_string() | unlimited,
            end_time => rfc3339_string() | unlimited,
            mfa => mfargs(),
            type => cron | every}.

ecron_result/0

-type ecron_result() :: {ok, name()} | {error, parse_error(), term()} | {error, already_exist}.

end_at/0

-type end_at() :: unlimited | calendar:time().

mfargs/0

-type mfargs() :: {M :: module(), F :: atom(), A :: [term()]}.

name/0

-type name() :: term().

option/0

-type option() :: {singleton, boolean()} | {max_count, pos_integer() | unlimited}.

options/0

-type options() :: [option()].

parse_error/0

-type parse_error() ::
          invalid_time | invalid_spec | month | day_of_month | day_of_week | hour | minute | second.

register/0

-type register() :: atom().

rfc3339_string/0

-type rfc3339_string() :: [byte(), ...].

start_at/0

-type start_at() :: unlimited | calendar:time().

statistic/0

-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()]}.

status/0

-type status() :: deactivate | activate.

Functions

activate(JobName)

-spec activate(name()) -> ok | {error, not_found}.

Equivalent to activate(ecron_local, Name).

activate(Register, JobName)

-spec activate(register(), name()) -> ok | {error, not_found}.

Activates a previously deactivated job. The job will resume from the current time.

Parameters:

  • Register - Process name where job is registered
  • JobName - Name of job to activate

Returns: ok | {error, not_found}

add(JobName, Spec, MFA)

-spec add(name(), crontab_spec(), mfargs()) -> ecron_result().

Equivalent to add(ecron_local, JobName, Spec, MFA).

add(Register, JobName, Spec, MFA)

-spec add(register(), name(), crontab_spec(), mfargs()) -> ecron_result().

Equivalent to add(Register, JobName, Spec, MFA, unlimited, unlimited, []).

add(JobName, Spec, MFA, Start, End, Opts)

-spec add(name(), crontab_spec(), mfargs(), start_at(), end_at(), options()) -> ecron_result().

Equivalent to add(ecron_local, name(), Spec, MFA, Start, End, []).

add(Register, JobName, Spec, MFA, Start, End, Opts)

-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 registered
  • JobName - Unique identifier for the job. Returns {error, already_exist} if duplicate
  • Spec - Crontab expression defining execution schedule
  • MFA - {Module, Function, Args} to execute when triggered
  • Start - Start time {Hour,Min,Sec} or unlimited for immediate start
  • End - End time {Hour,Min,Sec} or unlimited for no end
  • Opts - 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()}

add_with_count(Spec, MFA, RunCount)

-spec add_with_count(crontab_spec(), mfargs(), pos_integer()) -> ecron_result().

Equivalent to add_with_count(ecron_local, make_ref(), Spec, MFA, RunCount).

add_with_count(Register, JobName, 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}]).

add_with_time(JobName, Spec, MFA, Start, End)

-spec add_with_time(name(), crontab_spec(), mfargs(), start_at(), end_at()) -> ecron_result().

Equivalent to add(ecron_local, name(), Spec, MFA, Start, End, []).

add_with_time(Register, JobName, 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, []).

deactivate(JobName)

-spec deactivate(name()) -> ok | {error, not_found}.

Equivalent to deactivate(ecron_local, Name).

deactivate(Register, JobName)

-spec deactivate(register(), name()) -> ok | {error, not_found}.

Deactivates an existing job temporarily. The job can be reactivated using activate/2.

Parameters:

  • Register - Process name where job is registered
  • JobName - Name of job to deactivate

Returns: ok | {error, not_found}

delete(JobName)

-spec delete(name()) -> ok.

Equivalent to delete(ecron_local, Name).

delete(Register, JobName)

-spec delete(register(), name()) -> ok.

Deletes an existing job. If the job does not exist, it will be ignored.

Parameters:

  • Register - Process name where job is registered
  • JobName - Name of job to delete

Returns: ok

parse_spec(Spec, Num)

-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 parse
  • Num - Number of future trigger times to calculate

Returns: {ok, #{type => cron|every, crontab => parsed_spec, next => [rfc3339_string()]}} | {error, parse_error(), term()}

reload()

-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

send_after(Spec, Pid, Message)

-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 trigger
  • Dest - Destination pid() or registered name to receive message
  • Message - 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()}

send_interval(Spec, Pid, Message)

-spec send_interval(crontab_spec(), pid(), term()) -> ecron_result().

Equivalent to send_interval(ecron_local, make_ref(), Spec, Pid, Message, unlimited, unlimited, []).

send_interval(Register, Name, Spec, Pid, Message)

-spec send_interval(register(), name(), crontab_spec(), pid(), term()) -> ecron_result().

Equivalent to send_interval(ecron_local, name(), Spec, Pid, Message, unlimited, unlimited, []).

send_interval(Register, Name, Spec, Message, Start, End, Option)

-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).

send_interval(Register, JobName, Spec, Pid, 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 registered
  • JobName - Unique identifier for the job
  • Spec - Crontab expression defining execution schedule
  • Pid - Destination process ID or registered name
  • Message - Term to send on each trigger
  • Start - Start time {Hour,Min,Sec} or unlimited
  • End - End time {Hour,Min,Sec} or unlimited
  • Option - Same options as add/7

Returns: Same as add/7

statistic()

-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.

statistic(Register)

-spec statistic(register() | name()) -> [statistic()].

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.

statistic(Register, JobName)

-spec statistic(register(), name()) -> {ok, statistic()} | {error, not_found}.

Retrieves statistics for a specific job.

Parameters:

  • Register - Process name where job is registered
  • JobName - 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