Ecron

https://github.com/zhongwencool/ecron
Admin
A lightweight/efficient cron-like job scheduling library for Erlang/Elixir.
Tokens:3,187
Snippets:20
Trust Score:9.1
License:Apache-2.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Using Dedicated Ecron Registers (Start, Create, Delete)

Source: https://github.com/zhongwencool/ecron/blob/main/README.md

Illustrates how to start a dedicated Ecron register and then create and delete jobs associated with that specific register, allowing for isolated job management.

```Erlang
{ok, _}= ecron:start_link(YourRegister),
ecron:create(YourRegister, JobName, Spec, MFA, Options),
ecron:delete(YourRegister, JobName).
```

```Elixir
{:ok, _} = :ecron.start_link(YourRegister)
:ecron.create(YourRegister, job_name, spec, mfa, options)
:ecron.delete(YourRegister, job_name)
```

--------------------------------

### Mermaid Diagram: Ecron Job Execution Flow

Source: https://github.com/zhongwencool/ecron/blob/main/guide/implementation.md

This diagram illustrates the main flow of the Ecron application, detailing the initialization phase where the supervisor starts the worker, ETS is initialized, and jobs are loaded, followed by the main loop where jobs are retrieved from ETS, executed, and rescheduled.

```mermaid
flowchart TD
    A[ecron_sup] -->|starts| B[ecron]
    
    subgraph initialization
    B -->|init| C[ets:new - ordered_set]
    C -->|read config| D[local_jobs]
    D -->|calculate times| E["ets:insert with {NextTriggeredTime, Name}"]
    end
    
    subgraph main_loop
    E -->|loop| F[Get first entry from ETS]
    F -->|sleep until time| G["Execute(spawn) job in background"]
    G -->|delete old key| H[Calculate new time]
    H -->|"ets:insert new {NextTriggeredTime, Name}"| E
    end
```

--------------------------------

### Configuring Time Zone in Erlang

Source: https://github.com/zhongwencool/ecron/blob/main/README.md

Provides an example of how to configure the `time_zone` setting for Ecron within an Erlang `sys.config` file, allowing you to specify 'local' or 'utc'.

```Erlang
%% sys.config
[
   {ecron, [
      {time_zone, local} %% local or utc
   ]}
].
```

--------------------------------

### Configuring Ecron Jobs (Erlang)

Source: https://github.com/zhongwencool/ecron/blob/main/README.md

This configuration snippet for sys.config shows how to define local jobs for Ecron in an Erlang application. It includes examples using various crontab specifications (standard, with seconds, named schedules, intervals) and optional properties like start/end time, max count, singleton concurrency, and max runtime.

```Erlang
%% sys.config
[
   {ecron, [
      {local_jobs, [
         %% {JobName, CrontabSpec, {M, F, A}}
         %% {JobName, CrontabSpec, {M, F, A}, PropListOpts}
         %% CrontabSpec
            %%  1. "Minute Hour DayOfMonth Month DayOfWeek"
            %%  2. "Second Minute Hour DayOfMonth Month DayOfWeek"
            %%  3. @yearly | @annually | @monthly | @weekly | @daily | @midnight | @hourly
            %%  4. @every 1h2m3s
                  
         {basic, "*/15 * * * *", {io, format, ["Runs on 0, 15, 30, 45 minutes~n"]}},
         {sec_in_spec, "0 0 1-6/2,18 * * *", {io, format, ["Runs on 1,3,6,18 o'clock:~n"]}},
         {hourly, "@hourly", {io, format, ["Runs every(0-23) o'clock~n"]}},    
         {interval, "@every 30m", {io, format, ["Runs every 30 minutes"]}},         
         {limit_time, "*/15 * * * *", {io, format, ["Runs 0, 15, 30, 45 minutes after 8:20am~n"]}, [{start_time, {8,20,0}}, {end_time, {23, 59, 59}}]},
         {limit_count, "@every 1m", {io, format, ["Runs 10 times"]}, [{max_count, 10}]},
         {limit_concurrency, "@minutely", {timer, sleep, [61000]}, [{singleton, true}]},
         {limit_runtime_ms, "@every 1m", {timer, sleep, [2000]}, [{max_runtime_ms, 1000}]}
     ]}
    }
].
```

--------------------------------

### Adding Dedicated Ecron Registers to a Supervisor

Source: https://github.com/zhongwencool/ecron/blob/main/README.md

Provides examples for defining a child specification to include a dedicated Ecron register process under a supervisor, ensuring it is managed within the application's supervision tree.

```Erlang
YourRegister = your_register,
Children = [
  #{
        id => YourRegister,
        start => {ecron, start_link, [YourRegister]},
        restart => permanent,
        shutdown => 1000,
        type => worker
    }
]
```

```Elixir
children = [
  worker(:ecron, [YourRegister], restart: :permanent)
]
```

--------------------------------

### Configuring Ecron Jobs in Elixir config.exs (Global/Local Format)

Source: https://github.com/zhongwencool/ecron/blob/main/guide/Global.md

Provides an example configuration for ecron jobs in an Elixir `config.exs` file, illustrating the format used for both local and global jobs. It shows how to define a job with a name, crontab specification, and the MFA (Module, Function, Arguments) to execute. The comments illustrate various supported crontab formats.

```Elixir
# config/config.exs
config :ecron,  
  local_jobs: [
    # {job_name, crontab_spec, {module, function, args}}
    # {job_name, crontab_spec, {module, function, args}, PropListOpts}
    # CrontabSpec formats:
    #  1. "Minute Hour DayOfMonth Month DayOfWeek"
    #  2. "Second Minute Hour DayOfMonth Month DayOfWeek"
    #  3. @yearly | @annually | @monthly | @weekly | @daily | @midnight | @hourly
    #  4. @every 1h2m3s
    
    {:basic, "*/15 * * * *", {IO, :puts, ["Runs on 0, 15, 30, 45 minutes"]}}   
  ]
```

--------------------------------

### Defining Fixed Interval Schedules with @every in Erlang

Source: https://github.com/zhongwencool/ecron/blob/main/guide/crontab-spec.md

This Erlang snippet demonstrates how to define fixed interval schedules using the @every syntax followed by a duration string. It shows examples for running a task every 30 minutes and every 1 hour and 30 minutes.

```erlang
% Run every 30 minutes
"@every 30m"

% Run every 1 hour and 30 minutes
"@every 1h30m"
```

--------------------------------

### Running Tests with Rebar3

Source: https://github.com/zhongwencool/ecron/blob/main/README.md

Provides the shell command to execute property-based tests, common tests, and generate a coverage report for the Ecron project using the Rebar3 build tool.

```Shell
$ rebar3 do proper -c, ct -c, cover -v
```

--------------------------------

### Dynamically Managing Ecron Jobs (Create, Statistic, Delete)

Source: https://github.com/zhongwencool/ecron/blob/main/README.md

Shows how to programmatically create, retrieve statistics for, and delete an Ecron job using the ecron API in both Erlang and Elixir. Includes setting job options like max_runtime_ms.

```Erlang
JobName = every_4am_job,
MFA = {io, format, ["Run at 04:00 every day.\n"]},
Options = #{max_runtime_ms => 1000},
ecron:create(JobName, "0 4 * * *", MFA, Options).
Statistic = ecron:statistic(JobName),
ecron:delete(JobName),
Statistic.
```

```Elixir
job_name = :every_4am_job
mfa = {IO, :puts, ["Run at 04:00 every day.\n"]}
options = %{max_runtime_ms: 1000}
{:ok, ^job_name} = :ecron.create(job_name, "0 4 * * *", mfa, options)
statistic = :ecron.statistic(job_name)
:ecron.delete(job_name)
statistic
```

--------------------------------

### Sending One-Time Messages with Ecron (send_after)

Source: https://github.com/zhongwencool/ecron/blob/main/README.md

Demonstrates how to use ecron:send_after to schedule a one-time message delivery to a process based on a crontab specification, similar to erlang:send_after.

```Erlang
ecron:send_after("*/4 * * * * *", self(), hello_world),
receive Msg -> io:format("receive:~s~n", [Msg]) after 5000 -> timeout end.
```

```Elixir
:ecron.send_after("*/4 * * * * *", self(), :hello_world)
receive do msg -> IO.puts("receive: #{msg}") after 5000 -> :timeout end
```

--------------------------------

### Adding Ecron Dependency (Erlang)

Source: https://github.com/zhongwencool/ecron/blob/main/README.md

This snippet shows how to add the Ecron library as a dependency in an Erlang project's rebar.config file, specifying the required version.

```Erlang
  %% rebar.config
  {deps, [{ecron, "~> 1.1.0"}]}
```

--------------------------------

### Scheduling Interval Job with Elixir

Source: https://github.com/zhongwencool/ecron/blob/main/README.md

Shows how to schedule a recurring message to the current process using `:ecron.send_interval/3` in Elixir and includes a simple receive loop to handle the incoming messages.

```Elixir
:ecron.send_interval("*/4 * * * * *", self(), :hello_world)
loop = fn loop ->
  receive do
    msg -> 
      IO.puts("[#{Time.utc_now()}] receive: #{msg}")
      loop.(loop)
  after
    5000 -> :timeout
  end
end
loop.(loop)
```

--------------------------------

### Configuring Time Zone in Elixir

Source: https://github.com/zhongwencool/ecron/blob/main/README.md

Shows how to set the `time_zone` configuration for Ecron in an Elixir `config/config.exs` file, allowing selection between `:local` and `:utc`.

```Elixir
# config/config.exs
config :ecron,
  time_zone: :local  # :local or :utc
```

--------------------------------

### Adding Ecron Dependency (Elixir)

Source: https://github.com/zhongwencool/ecron/blob/main/README.md

This snippet demonstrates how to include the Ecron library as a dependency in an Elixir project's mix.exs file within the deps function, specifying the required version.

```Elixir
  # mix.exs
  def deps do
    [{:ecron, "~> 1.1.0"}]
  end
```

--------------------------------

### Configuring Log Level in Elixir

Source: https://github.com/zhongwencool/ecron/blob/main/README.md

Demonstrates how to set the `log_level` configuration for Ecron's telemetry logging in an Elixir `config/config.exs` file, specifying the verbosity of logged events.

```Elixir
# config/config.exs
config :ecron,
  # :none | :all | :alert | :error
  log_level: :all
```

--------------------------------

### Scheduling Interval Job with Erlang

Source: https://github.com/zhongwencool/ecron/blob/main/README.md

Demonstrates how to use `ecron:send_interval/3` to schedule a recurring message to the current process and includes a simple receive loop to process the messages.

```Erlang
ecron:send_interval("*/4 * * * * *", self(), hello_world),
Loop = fun(Loop) ->
  receive
    Msg -> 
      io:format("[~p] receive: ~s~n", [erlang:time(), Msg]),
      Loop(Loop)
  after
    5000 -> timeout
  end
end,
Loop(Loop).
```

--------------------------------

### Configuring Static Ecron Jobs in Elixir

Source: https://github.com/zhongwencool/ecron/blob/main/README.md

Demonstrates how to define recurring jobs statically within the application's configuration file (config/config.exs). Jobs are defined as tuples specifying the name, crontab specification, MFA (Module, Function, Arguments), and optional properties.

```Elixir
config :ecron, 
  local_jobs: [
    # {job_name, crontab_spec, {module, function, args}}
    # {job_name, crontab_spec, {module, function, args}, PropListOpts}
    # CrontabSpec formats:
    #  1. "Minute Hour DayOfMonth Month DayOfWeek"
    #  2. "Second Minute Hour DayOfMonth Month DayOfWeek"
    #  3. @yearly | @annually | @monthly | @weekly | @daily | @midnight | @hourly
    #  4. @every 1h2m3s
    
    {:basic, "*/15 * * * *", {IO, :puts, ["Runs on 0, 15, 30, 45 minutes"]}},
    {:sec_in_spec, "0 0 1-6/2,18 * * *", {IO, :puts, ["Runs on 1,3,6,18 o'clock:"]}},
    {:hourly, "@hourly", {IO, :puts, ["Runs every(0-23) o'clock"]}},
    {:interval, "@every 30m", {IO, :puts, ["Runs every 30 minutes"]}},
    {:limit_time, "*/15 * * * *", {IO, :puts, ["Runs 0, 15, 30, 45 minutes after 8:20am"]}, [start_time: {8,20,0}, end_time: {23, 59, 59}]},
    {:limit_count, "@every 1m", {IO, :puts, ["Runs 10 times"]}, [max_count: 10]},
    {:limit_concurrency, "@minutely", {Process, :sleep, [61000]}, [singleton: true]},
    {:limit_runtime_ms, "@every 1m", {Process, :sleep, [2000]}, [max_runtime_ms: 1000]}
  ]
```

--------------------------------

### Configuring Log Level in Erlang

Source: https://github.com/zhongwencool/ecron/blob/main/README.md

Illustrates how to configure the `log_level` setting for Ecron's telemetry logging within an Erlang `sys.config` file, controlling which events are logged.

```Erlang
%% sys.config
  [
   {ecron, [
    %% none | all | alert | error | notice 
      {log_level, all}
   ]}
].
```

--------------------------------

### Configuring Global Jobs in Erlang sys.config

Source: https://github.com/zhongwencool/ecron/blob/main/guide/Global.md

Demonstrates how to define global jobs for the ecron application within an Erlang `sys.config` file. It shows the structure for defining a job with a name, crontab specification, and the MFA (Module, Function, Arguments) to execute. The comments illustrate various supported crontab formats.

```Erlang
%% sys.config
[
   {ecron, [
      {global_jobs, [
         %% {JobName, CrontabSpec, {M, F, A}}
         %% {JobName, CrontabSpec, {M, F, A}, PropListOpts}
         %% CrontabSpec
            %%  1. "Minute Hour DayOfMonth Month DayOfWeek"
            %%  2. "Second Minute Hour DayOfMonth Month DayOfWeek"
            %%  3. @yearly | @annually | @monthly | @weekly | @daily | @midnight | @hourly
            %%  4. @every 1h2m3s
                  
         {basic, "*/15 * * * *", {io, format, ["Runs on 0, 15, 30, 45 minutes~n"]}}         
     ]}     
    }
].
```

--------------------------------

### Illustrating Crontab Field Structure

Source: https://github.com/zhongwencool/ecron/blob/main/guide/crontab-spec.md

This snippet provides a visual representation of the standard Crontab expression format, showing the order and meaning of the 5 or 6 time unit fields.

```text
# ┌────────────── second (optional)
# │ ┌──────────── minute
# │ │ ┌────────── hour
# │ │ │ ┌──────── day of month
# │ │ │ │ ┌────── month
# │ │ │ │ │ ┌──── day of week
# │ │ │ │ │ │
# │ │ │ │ │ │
# 0 * * * * *
```
Tokens:
Raw