Shinjuku.rb#43 research -- javan/whenever

whenever.md

Wheneverの調査

Shinjuku.rb #43

Wheneverとは、明快なシンタックスとcron jobを提供するgemである。

使い方

インストール

グローバルにinstall

$ gem install whenever

or Gemfileに書く

+ gem 'whenever', require: false

DSLを記述

$ wheneverize .

→ config/schedule.rb に設定ファイルができる

書き方

set :output, "/path/to/my/cron_log.log"

every 2.hours do
  command "/usr/bin/some_great_command"
  runner "MyModel.some_method"
  rake "some:great:rake:task"
end

みたいなDSLで書ける。

cronの記述に変換 / 実際にcrontabを更新する

$ wheneverize --update-crontab

直感的なDSLでcronを書けるよ！

実装

大体以下のようにできている

• wheneverize
  • config/shedule.rbを直で出力
    • テンプレートはbin/wheneverizeに直接書いてある
• whenever
  • オプションのparse
  • Whenever::CommandLine(self.execute -> initialize -> run) -> Whenever.cron -> Whenever::JobList (initialize -> generate_cron_output)の順でたどる。
    • まず、defaultの設定(DSLで書かれている)を読み込む (A)
      • defaultの設定ファイル(lib/whenever/setup.rb)
  • ユーザー定義の設定を読み込む
  • マージ

DSLの解釈

(A)の部分にて、 https://github.com/javan/whenever/blob/c7675c81d34131f7107b2930c207c9b994895a08/lib/whenever/job_list.rb#L24

instance_eval(setup, setup_file)

とある。

読み込んだ中身をそのままevalしている -> lib/whenever/job_list.rbのメソッドがそのまま、DSLとして使える

• set
• env
• every
• job_type

この中でもset, job_typeはメソッドの中でさらにメソッドを定義するというメタプロなことをしている

• set : https://github.com/javan/whenever/blob/c7675c81d34131f7107b2930c207c9b994895a08/lib/whenever/job_list.rb#L28-L35
• job_type : https://github.com/javan/whenever/blob/c7675c81d34131f7107b2930c207c9b994895a08/lib/whenever/job_list.rb#L28-L35

job_type はどういうテンプレートを使うか定義できるものだが、defaultのDSLsetup.rb内で下記4つが動的に定義されている

• command
• rake
• script
• runner

everyメソッドはブロックをスコープのように扱うことでcronの時間情報を閉じ込めている(@current_time_scopeに時間情報を持っている) つまり、

every 2.days do
  command 'echo "hello, world!!"'
end

のようなDSLは、@current_time_scope = 2.daysとして、その後のparseが行われる。

• 実際のcrontab形式への変換はgenerate_cron_outputメソッド内、cron_jobsメソッドで行っている
  • generate_cron_outputでは、環境変数の変換も別に行っている(environment_variables)
• さらに深掘りすると、Whenever::Output::Cron.outputというのが出てくる
• Whenever::Output::Cron.output -> Whenever::Output::Cron.enumerate -> Whenever::Output::Cron#output で追う。
  • Whenever::Output::Cron#time_in_cron_syntaxが、wheneverの記法から、cronの記法に必要あれば変換しているところ(時間情報) 　　- 場合分けのところが勉強になる(case文: https://gist.github.com/treby/78a1c6bf9c145970ea8f1e4af2cbc73d#gistcomment-1931738)
  • コマンド部分はWhenever::Job#outputにてやっている
    • templateに変数をあてはめることをしている
    • これら二つを組み合わせてDSLからcronの記述ができる

crontabの更新

• lib/whenever/command_line.rb内でやっている  - 特定のマジックコメントでどの範囲を更新するか制御している

wheneverの使い所

Schedulingツールを使う上で考慮すべきこと：処理の重複(ロック)

• プロセス内ロック  - 単一のプロセス内では重複しないことが保証されている
• プロセス間ロック・サーバ内ロック  - 同一のサーバ内では処理が重複しないことが保証されている
• サーバ間ロック  - サーバ群の中で処理が重複しないことが保証されている

wheneverはあくまでcrontabを更新するためのgem。上の内では「プロセス間ロック・サーバ内ロック」にあたる。単一のサーバでのみ稼働するシステムでは有用だが、複数サーバを使うようなケースでは、どのサーバで稼働させるかを考慮しなければならない。

Whenever::JobListを見てみる

    def initialize(options)
      @jobs, @env, @set_variables, @pre_set_variables = {}, {}, {}, {}

      if options.is_a? String
        options = { :string => options }
      end

      pre_set(options[:set])

      @roles = options[:roles] || []

      setup_file = File.expand_path('../setup.rb', __FILE__)
      setup = File.read(setup_file)
      schedule = if options[:string]
        options[:string]
      elsif options[:file]
        File.read(options[:file])
      end

      instance_eval(setup, setup_file)
      instance_eval(schedule, options[:file] || '<eval>')
    end

    def pre_set(variable_string = nil)
      return if variable_string.nil? || variable_string == ""

      pairs = variable_string.split('&')
      pairs.each do |pair|
        next unless pair.index('=')
        variable, value = *pair.split('=')
        unless variable.nil? || variable == "" || value.nil? || value == ""
          variable = variable.strip.to_sym
          set(variable, value.strip)
          @pre_set_variables[variable] = value
        end
      end
    end

• pre_set methodによって、--setで指定されたvariableがセットされる key1=value1&key2=value2...の形式
  • set methodは何の用途に使われているのだろう
• roleで何やら指定している
• setup.rbを読んでinstance_evalしている → ここでsetが出て来る。

set -> instance_variableとして設定されている

かつ、attr_readerが設定されている

set methodとjob_typeメソッドが肝か？

job_type：4つある

• command
• rake
• script
• runner

job_type :command, ":task :output"
job_type :rake,    "cd :path && :environment_variable=:environment :bundle_command rake :task --silent :output"
job_type :script,  "cd :path && :environment_variable=:environment :bundle_command script/:task :output"
job_type :runner,  "cd :path && :bundle_command :runner_command -e :environment ':task' :output"

setup を読み込んだ後にschedule (file or string)を読み込んでいる(by instance_eval)

instance_evalの第二引数にファイル名を与えられるっぽい
https://docs.ruby-lang.org/ja/latest/method/BasicObject/i/instance_eval.html

つまり、job_listのpublicメソッドがそのまま、wheneverのDSLとして使える

singleton_classってなんだ？

http://ref.xaio.jp/ruby/classes/object/singleton_class

singleton_classメソッドは、オブジェクトの特異クラスを返します。

特異クラスとは

http://qiita.com/fukumone/items/95117f418dec590ebbc8
特異メソッドのためのクラス：特異メソッド → オブジェクトに直接生やしたやつ、つまりsetで拡張したクラスのことかしら

ファイルを解釈したら、generate_cron_outputを実行する

def generate_cron_output
  [environment_variables, cron_jobs].compact.join
end

environment_variables

cronの環境変数類

def environment_variables
  return if @env.empty?
  output = []
  @env.each do |key, val|
    output << "#{key}=#{val.nil? || val == "" ? '""' : val}\n"
  end
  output << "\n"

  output.join
end

cron_job

def cron_jobs
  return if @jobs.empty?

  shortcut_jobs = []
  regular_jobs = []

  output_all = roles.empty?
  @jobs.each do |time, jobs|
    jobs.each do |job|
      next unless output_all || roles.any? do |r|
        job.has_role?(r)
      end
      Whenever::Output::Cron.output(time, job) do |cron|
        cron << "\n\n"

        if cron[0,1] == "@"
          shortcut_jobs << cron
        else
          regular_jobs << cron
        end
      end
    end
  end

  shortcut_jobs.join + combine(regular_jobs).join
end

Whenever::Output::Cron がcronの変換処理の実体か
その前に@jobsの実体を調べる

@jobsについて

• job_type methodの中定義されているメソッド内でセットされている(デフォルトでcommand, rake, script, runner)。
• current_time_scopeごとに登録されている→ 同一時間内でまとめるためだろう

Whenever::Job.newなるものが出てきたぞ

Whenever::Job#initialize

    def initialize(options = {})
      @options = options
      @at                               = options.delete(:at)
      @template                         = options.delete(:template)
      @job_template                     = options.delete(:job_template) || ":job"
      @roles                            = Array(options.delete(:roles))
      @options[:output]                 = options.has_key?(:output) ? Whenever::Output::Redirection.new(options[:output]).to_s : ''
      @options[:environment_variable] ||= "RAILS_ENV"
      @options[:environment]          ||= :production
      @options[:path]                   = Shellwords.shellescape(@options[:path] || Whenever.path)
    end

一旦戻ってWhenever::Output::Cron を見る (lib/whenever/cron.rb)

outputメソッド / timesにはcurrent_time_scopeが入る

def self.output(times, job)
  enumerate(times).each do |time|
    enumerate(job.at, false).each do |at|
      yield new(time, job.output, at).output
    end
  end
end

まず、enumerateから / timeを解釈しているのかな

def self.enumerate(item, detect_cron = true)
  if item and item.is_a?(String)
    items =
      if detect_cron && item =~ REGEX
        [item]
      else
        item.split(',')
      end
  else
    items = item
    items = [items] unless items and items.respond_to?(:each)
  end
  items
end

次に#initializeをみる

def initialize(time = nil, task = nil, at = nil)
  @at_given = at
  @time = time
  @task = task
  @at     = at.is_a?(String) ? (Chronic.parse(at) || 0) : (at || 0)
end

つまり、少なくとも組み込みクラスの範囲において、===演算子が==演算子よりも厳密な同値判定であるケースは皆無というわけです。Rubyにおける===演算子は、他の言語における===演算子とは全く別物と割り切るべきである、と言えます。

へー

timeはcurrent_time_scopeが、atはjobが持っているパラメータ

Whenever::Output::Cron#outputをみる

def output
  [time_in_cron_syntax, task].compact.join(' ').strip
end

      def time_in_cron_syntax
        @time = @time.to_i if @time.is_a?(Numeric) # Compatibility with `1.day` format using ruby 2.3 and activesupport
        case @time
          when REGEX  then @time # raw cron syntax given
          when Symbol then parse_symbol
          when String then parse_as_string
          else parse_time
        end
      end

こんなcase文の書き方できるんや
http://qiita.com/giiko_/items/c75833cd47e41c9b8605

http://d.hatena.ne.jp/shibason/20090617/1245231492

基本的には、Whenever::Output::Cronで組み立てられているのか

Whenever::JobList#generate_cron_output

cron_jobs

shortcut_jobs / regular_jobsの違い?

• プロセス内ロック
  • それぞれのプロセスで実行したい
• プロセス間ロック
  • サーバ内でユニークにしたい(crontab)
  • file lock
• サーバ間ロック
  • サーバ群でユニークにしたい