Getting Started

Install

Currently Koyomi is available on GitHub and CPAN.

Koyomi depends on some external modules. And all its dependencies are written in cpanfile.

From GitHub

You can download archive files from https://github.com/progrhyme/perl5-App-Koyomi/releases .

wget https://github.com/progrhyme/perl5-App-Koyomi/archive/vX.Y.Z.tar.gz
tar xvzf perl5-App-Koyomi-vX.Y.Z.tar.gz
cd perl5-App-Koyomi-vX.Y.Z

If you need to install dependent modules of Koyomi, install them by cpanfile.

cpanm --installdeps .

Or you can use carton to install modules under local/ directory.

carton install

From CPAN

cpanm App::Koyomi

This installs all dependent modules of Koyomi into your current perl.

top

Configure

The default configuration file is config/default.toml.
You can edit the file for customization. Or when you want to use the configuration file in another path, you can specify the path by environmental variable $KOYOMI_CONFIG_PATH.

The following content shows available configuration parametes in the file.

General Parameters

time_zone = "Asia/Tokyo" # Local time zone is used when not specified

# Enable some debug parameters (see "Debug Parameters" below)
# Don't set "true" on production environment.
debug_mode = true

Logging Parameters

[log]
debug   = true            # Enable debug log
console = true            # Output to stderr
file    = true            # Output to log file
file_path = /path/to/log  # Log file path

Job Scheduling Parameters

[worker]
interval_minutes = 1 # Worker interval

# Must be shorter than interval_minutes
minimum_interval_seconds = 30

[schedule]
update_interval_seconds = 120 # How often it re-fetch schedule from Datastore

[job]
# Must be shorter than worker.minimum_interval_seconds
lock_ttl_seconds = 25

When worker.interval_minutes = 1, koyomi worker wakes up and execute scheduled jobs at that time once a minute like cron daemon. You can customize the parameter for longer intervals.

Koyomi worker tries to wake up when the second of time equals 00 (ex: T09:03:00). But it sleeps at least worker.minimum_interval_seconds every after spawning jobs once a worker.interval_minutes.

So if you start koyomi worker at T09:02:55 and given worker.minimum_interval_seconds = 30, next time wokrer wakes up at T09:03:25, after that T09:04:00, then T09:05:00, ….

Koyomi worker fetches jobs schedule from Datastore on start-up, and refetch it every after schedule.update_interval_seconds.

Multiple koyomi workers are supposed to run with the same schedule datastore.
Only one koyomi worker runs a certain job at a time.

When a koyomi worker wins to run a job, it records on datastore the “time” and the “hostname” and the “process id”.
On the other hand, another koyomi worker tries to run the job around the time.
But with the job record in datastore, it knows the other worker has run it.
When one worker has run a job within job.lock_ttl_seconds, the other workers quit to run the job.

Data Source Parameters

[datasource.module]
job       = "Teng"
semaphore = "Teng"
#semaphore = "None"

[datasource.connector]
dsn      = "dbi:mysql:database=koyomi;host=127.0.0.1;port=3306"
#dsn      = "dbi:SQLite:koyomi.sqlite"
user     = "root"
password = ""

# Can override for each entity
[datasource.connector.job]
dsn  = ...
user = "foo"
password = "xxx"

[datasource.connector.semaphore]
# Can override "datasource.connector", too.

Datasource job stands for job schedules.
Datasource semaphore stands for the record and lock entity which controls if one koyomi worker can run a job or not.

You can specify perl module to access each entity of datastore.
Teng modules are implemented for both “job” and “semaphore” datastore.

None module which is only for “semaphore” satisfies the required interface of “semaphore” module, but actually does nothing about “semaphore”.
None module is to be used when worker runs in a standalone mode while “job” is on local datastore like SQLite. Because exclusive control for job execution is not required when there is only single worker.

Set Up Datastore

Here are descriptions about how to set up datastore.

MySQL

MySQL database schema is available at schema/mysql/koyomi.ddl in the source code repository.

SQLite

SQLite database schema is also available at schema/sqlite/koyomi.ddl in the source code repository.

Job Registration

You can register jobs by koyomi-cli (See below).
Note that you have to prepare configuration file with right datasource settings beforehand.

Usage

Worker

You can launch koyomi worker in the way like this:

koyomi -c /path/to/config.toml [--debug]

You can see details of command-line options by koyomi --help.

CLI

koyomi-cli is a handy command-line interface for CRUD of jobs.
Run koyomi-cli help to see how to use this script.