clockwork

clockwork/schedule

Types

Message

</>

Internal message types for scheduler communication

pub type Message {
  Run
  Stop
}

Constructors 

  • Run
  • Stop

Schedule

</>

Represents a running scheduled job that can be controlled (e.g., stopped).

A Schedule is returned when you successfully start a scheduler with schedule.start(). It contains an internal reference to the running process and can be used to stop the job with schedule.stop().

Example

// Start a scheduler and get a running schedule
let assert Ok(schedule) = schedule.start(my_scheduler)

// Later, stop the running schedule
schedule.stop(schedule)

pub type Schedule {
  Schedule(subject: process.Subject(Message))
}

Constructors 

  • Schedule(subject: process.Subject(Message))

Scheduler

opaque </>

Configuration for a scheduled job, created with new and configured with builder methods.

The Scheduler type is opaque, meaning its internal structure is hidden from users of the library. This allows us to add new configuration options without breaking existing code. Create a scheduler with new and then use the builder methods to configure it (e.g., with_logging, with_telemetry, etc.).

Builder pattern

// Create a new scheduler for a job
let scheduler = schedule.new("my-job", my_cron, my_job_function)
  |> schedule.with_logging()
  |> schedule.with_telemetry()
  |> schedule.with_time_offset(calendar.local_offset())
  |> schedule.with_retry(max_attempts: 3, base_delay_ms: 1000)

pub opaque type Scheduler

Functions

new

</> 
pub fn new(
  id: String,
  cron: Cron,
  job: fn() -> Result(Nil, Nil),
) -> Scheduler

Create a new scheduler with default settings.

This is the starting point for configuring a scheduled job. After creating a scheduler with this function, you can use the builder methods to customize its behavior.

Parameters

  • id: A unique identifier for this scheduled job. This will appear in logs and telemetry.
  • cron: A cron expression that defines when the job should run.
  • job: The function to execute on the schedule. It should take no arguments and return a Result.

Default Settings

  • Logging: Disabled
  • Telemetry: Disabled
  • Time offset: UTC
  • Retry: Disabled

Example

let daily_job = 
  schedule.new(
    "daily-summary",
    // Run at midnight every day
    clockwork.from_string("0 0 * * *") |> result.unwrap(clockwork.default()),
    fn() { 
      // Return Ok(Nil) on success, Error(Nil) on failure
      case generate_daily_summary() {
        True -> Ok(Nil)
        False -> Error(Nil)
      }
    }
  )

start

</> 
pub fn start(
  scheduler: Scheduler,
) -> Result(Schedule, StartError)

Start the scheduler and begin running the job according to the cron schedule.

This function launches the scheduler as an actor process and returns a Schedule that can be used to control the running job. The scheduler will continue running until explicitly stopped with schedule.stop().

Parameters

  • scheduler: The configured scheduler to start.

Returns

  • Ok(Schedule): If the scheduler was successfully started.
  • Error(actor.StartError): If the scheduler failed to start.

Example

let scheduler = 
  schedule.new("my-job", my_cron, my_job_function)
  |> schedule.with_logging()

case schedule.start(scheduler) {
  Ok(running_schedule) -> {
    io.println("Job started successfully!")
    // Later...
    schedule.stop(running_schedule)
  }
  Error(error) -> io.println("Failed to start job: " <> error)
}

stop

</> 
pub fn stop(schedule: Schedule) -> Nil

Stop a running scheduled job.

This function sends a stop message to the scheduler actor, which will gracefully terminate the job and clean up any resources. After stopping a job, it cannot be restarted - you must create a new scheduler and start it again.

Parameters

  • schedule: The running schedule to stop, obtained from schedule.start().

Example

let assert Ok(running_schedule) = schedule.start(scheduler)

// Run the job for a while...
process.sleep(duration.seconds(60))

// Then stop it
schedule.stop(running_schedule)

with_logging

</> 
pub fn with_logging(scheduler: Scheduler) -> Scheduler

Enable logging for this scheduler.

When logging is enabled, the scheduler will log information about job execution, including when jobs start and stop, and any errors that occur. This is useful for debugging and monitoring scheduled jobs.

Parameters

  • scheduler: The scheduler to enable logging for.

Example

let scheduler = 
  schedule.new("my-job", my_cron, my_job_function)
  |> schedule.with_logging()

with_retry

</> 
pub fn with_retry(
  scheduler: Scheduler,
  max_attempts: Int,
  base_delay: Duration,
  backoff_factor backoff_factor: Float,
  max_delay max_delay: Duration,
) -> Scheduler

Configure retry behavior for a scheduler.

When a job fails (returns Error), the scheduler will retry it according to the configured retry strategy. Retries use exponential backoff with configurable parameters to avoid overwhelming the system.

Parameters

  • scheduler: The scheduler to configure retries for.
  • max_attempts: Maximum number of retry attempts (not including the initial try).
  • base_delay: Initial delay before the first retry.
  • backoff_factor: Multiplier for each subsequent retry delay. Defaults to 2.0 (double).
  • max_delay: Maximum delay between retries. Defaults to 1 hour.

Example

// Retry up to 3 times with 1 second initial delay
let scheduler = 
  schedule.new("retry-job", my_cron, my_fallible_job)
  |> schedule.with_retry(max_attempts: 3, base_delay_ms: 1000)

// Custom exponential backoff with lower multiplier and max delay
let custom_retry = 
  schedule.new("custom-retry", my_cron, my_job)
  |> schedule.with_retry(
    max_attempts: 5, 
    base_delay: duration.milliseconds(500),
    backoff_factor: 1.5,
    max_delay: duration.milliseconds(30_000)
  )

with_telemetry

</> 
pub fn with_telemetry(scheduler: Scheduler) -> Scheduler

Enable OpenTelemetry instrumentation for this scheduler.

When telemetry is enabled, the scheduler will create spans for each job execution with detailed information about the job, including timestamp, time of day, and other attributes. This is useful for monitoring and tracing job execution in a distributed system.

Parameters

  • scheduler: The scheduler to enable telemetry for.

Requirements

For telemetry to work, you must have OpenTelemetry configured in your application. The Clockwork library uses the glotel package for instrumentation.

Example

let scheduler = 
  schedule.new("my-job", my_cron, my_job_function)
  |> schedule.with_telemetry()

with_time_offset

</> 
pub fn with_time_offset(
  scheduler: Scheduler,
  offset: Duration,
) -> Scheduler

Set a custom time offset for this scheduler.

The time offset is used to determine when jobs should run in a specific timezone. By default, the scheduler uses UTC time. This function allows you to specify a different timezone offset.

Parameters

  • scheduler: The scheduler to set the time offset for.
  • offset: The time offset to use, as a duration (positive or negative).

Example

// Use local time zone
let scheduler = 
  schedule.new("my-job", my_cron, my_job_function)
  |> schedule.with_time_offset(calendar.local_offset())

// Use Eastern Time (UTC-5)
let eastern_time = 
  schedule.new("us-east-job", my_cron, my_job_function)
  |> schedule.with_time_offset(duration.hours(-5))
✨ Search Document